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.

Practice

1. What is the main purpose of the try_files directive in nginx?

easy

A. To check multiple files or paths in order and serve the first found

B. To restart the nginx server automatically

C. To define user permissions for files

D. To log errors in a custom file

Solution

1. Step 1: Understand the role of try_files

   The try_files directive checks a list of files or paths one by one.

2. Step 2: Identify its purpose

   It serves the first file found or falls back to a default if none exist.

3. Final Answer:

   To check multiple files or paths in order and serve the first found -> Option A

4. Quick Check:

   try_files = check files in order [OK]

Hint: Remember: try_files tries files one by one until success [OK]

Common Mistakes:

• Thinking try_files restarts nginx
• Confusing try_files with permission settings
• Assuming try_files logs errors

2. Which of the following is the correct syntax for the try_files directive in nginx?

easy

A. try_files file1 file2 fallback;

B. try_files file1 file2 =404;

C. try_files file1, file2, fallback;

D. try_files (file1 file2 fallback);

Solution

1. Step 1: Recall try_files syntax rules

   The try_files directive lists files separated by spaces, ending with a fallback like =404.

2. Step 2: Identify correct syntax

   try_files file1 file2 =404; uses spaces and ends with =404, which is valid syntax.

3. Final Answer:

   try_files file1 file2 =404; -> Option B

4. Quick Check:

   try_files syntax uses spaces and fallback [OK]

Hint: Use spaces, no commas or parentheses, end with fallback [OK]

Common Mistakes:

• Using commas between file names
• Adding parentheses around files
• Omitting fallback or using wrong fallback syntax

3. Given this nginx config snippet:

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

What happens when a user requests /about and /about is not a file but /about/ is a directory?

medium

A. nginx serves the /about file

B. nginx returns a 404 error

C. nginx serves the /about/ directory index

D. nginx serves /index.html fallback

Solution

1. Step 1: Understand try_files order

   nginx first checks if /about file exists, then /about/ directory.

2. Step 2: Apply to given request

   /about file is missing, but /about/ directory exists, so nginx serves the directory index.

3. Final Answer:

   nginx serves the /about/ directory index -> Option C

4. Quick Check:

   try_files checks files then directories [OK]

Hint: try_files checks files then directories in order [OK]

Common Mistakes:

• Assuming it serves /index.html fallback immediately
• Thinking it returns 404 if file missing
• Ignoring directory check after file check

4. Identify the error in this nginx config snippet:

location / {
  try_files $uri, $uri/, /fallback.html;
}

medium

A. Using commas between file names is invalid syntax

B. Missing semicolon at the end of try_files

C. Fallback file must be =404, not /fallback.html

D. Variables like $uri cannot be used in try_files

Solution

1. Step 1: Check try_files syntax

   try_files expects file names separated by spaces, not commas.

2. Step 2: Identify error in snippet

   The commas after $uri and $uri/ cause syntax error.

3. Final Answer:

   Using commas between file names is invalid syntax -> Option A

4. Quick Check:

   try_files uses spaces, no commas [OK]

Hint: No commas in try_files list, only spaces [OK]

Common Mistakes:

• Adding commas between file names
• Confusing fallback with error codes
• Thinking variables are disallowed in try_files

5. You want nginx to try serving /images/$uri, then /images/default.png if the first doesn't exist. Which try_files directive correctly implements this?

hard

A. try_files /images/$uri /images/default.png /index.html;

B. try_files $uri /images/default.png;

C. try_files /images/$uri /images/default.png=404;

D. try_files /images/$uri /images/default.png;

Solution

1. Step 1: Understand file paths in try_files

   To check /images/$uri first, it must be the first argument.

2. Step 2: Choose fallback file

   If the first file is missing, serve /images/default.png as fallback.

3. Step 3: Validate options

   try_files /images/$uri /images/default.png; matches this logic exactly without extra fallbacks or error codes.

4. Final Answer:

   try_files /images/$uri /images/default.png; -> Option D

5. Quick Check:

   try_files lists files in order, fallback last [OK]

Hint: List files in order, fallback last without extra codes [OK]

Common Mistakes:

• Using $uri without /images/ prefix
• Adding unnecessary fallback like =404
• Ending with unrelated fallback like /index.html