Try_files directive in Nginx - Commands & Configuration

Introduction

Sometimes a web server needs to check if a file exists before serving it. The try_files directive in nginx helps by trying multiple file paths in order and serving the first one it finds. This avoids errors and improves user experience by providing fallback options.

When you want to serve static files but provide a default page if the file is missing.

When you have a single-page application and want all unknown URLs to load index.html.

When you want to check multiple locations for a file before returning a 404 error.

When you want to redirect requests to a script if the file does not exist.

When you want to improve performance by avoiding unnecessary error handling.

Config File - nginx.conf

nginx.conf

server {
    listen 80;
    server_name example.com;

    root /var/www/html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

This configuration sets up a server listening on port 80 for example.com.

The root defines where files are served from.

The location / block uses try_files to check if the requested URI is a file ($uri) or a directory ($uri/), and if neither exists, it serves /index.html as a fallback.

Commands

This command tests the nginx configuration file for syntax errors before applying changes.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

This command reloads nginx to apply the new configuration without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

This command checks the HTTP headers returned when requesting a file that does not exist, to verify fallback behavior.

Terminal

curl -I http://example.com/nonexistentfile

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Wed, 05 Jun 2024 12:00:00 GMT

Content-Type: text/html

Content-Length: 1256

Connection: keep-alive

→

-I - Fetch only HTTP headers to quickly check response status

Key Concept

If you remember nothing else from this pattern, remember: try_files checks multiple file paths in order and serves the first one found, providing graceful fallback handling.

Common Mistakes

Using try_files without a fallback file or URI at the end.

If none of the files exist, nginx returns a 404 error without a fallback, which may not be desired.

Always include a fallback file or URI as the last argument in try_files, like /index.html or =404.

Not reloading nginx after changing the configuration.

Changes won't take effect until nginx reloads, so the old behavior continues.

Run 'sudo nginx -t' to test and then 'sudo systemctl reload nginx' to apply changes.

Using try_files with incorrect root or alias paths causing file not found.

If root or alias is misconfigured, try_files won't find files even if they exist.

Ensure root or alias matches the actual file system path where files are stored.

Summary

Use try_files to check multiple file paths in order and serve the first existing one.

Always include a fallback file or URI to handle missing files gracefully.

Test nginx configuration with 'nginx -t' and reload with 'systemctl reload nginx' after changes.