Home / Nginx / Fix Nginx try_files $request_filename Not Working - 404 and Fallback Errors

Nginx

Fix Nginx try_files $request_filename Not Working - 404 and Fallback Errors

Resolve Nginx `try_files $request_filename` returning 404 errors, fallback not working, and SPA routing failures with correct path and alias configuration.

Published: Nov 28, 20259 min readBy FixWikiHub Editorial Team

Abstract illustration for a troubleshooting knowledge base category.

# Nginx try_files $request_filename Not Working

The try_files directive should gracefully handle missing files and fallback to alternative content, but instead you get 404 errors, infinite redirect loops, or all requests going to the fallback. A common search case is try_files $request_filename, especially when alias is involved. Understanding how try_files evaluates its arguments and interacts with other directives is critical for proper fallback behavior.

Introduction

This article covers troubleshooting steps and solutions for Fix Nginx try_files $request_filename Not Working - 404 and Fallback Errors. The error typically occurs in production environments and can cause service disruptions if not addressed promptly.

Symptoms

Common error messages include:

nginx

location / {
    root /var/www/html;
    try_files $uri $uri/ /index.html;
}

nginx

location / {
    try_files /index.html $uri $uri/;  # Wrong order
}

nginx

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

Common Causes

Configuration misconfiguration
Missing or incorrect credentials
Network connectivity issues
Version compatibility problems
Resource exhaustion or limits
Permission or access denied

Step-by-Step Fix

1.Check logs for specific error messages
2.Verify configuration settings
3.Test network connectivity
4.Review recent changes
5.Apply corrective action
6.Verify the fix

Understanding Try_Files Behavior

1.try_files checks each path in order:
2.Checks if file exists (using $uri as path)
3.Checks if directory exists (using $uri/ as path)
4.Falls back to the last argument (URI or named location)

Basic example: ``nginx location / { root /var/www/html; try_files $uri $uri/ /index.html; }

1.Request /about:
2.Check /var/www/html/about - file? No
3.Check /var/www/html/about/ - directory? No
4.Internal redirect to /index.html

Common Cause 1: Order of Arguments Matters

Arguments are checked in sequence; wrong order breaks logic.

Problematic config: ``nginx location / { try_files /index.html $uri $uri/; # Wrong order }

Every request immediately falls back to /index.html. $uri never checked.

Solution: Check specific first, fallback last: ``nginx location / { try_files $uri $uri/ /index.html; }

Common Cause 2: Named Location vs URI Fallback

The last argument behavior differs.

URI fallback (starts internal redirect): ``nginx try_files $uri $uri/ /index.html; # Falls back to /index.html, processed by location matching

Named location fallback: ```nginx try_files $uri $uri/ @fallback;

location @fallback { proxy_pass http://backend; } ```

Named location bypasses normal location matching, goes directly to the named block.

Problematic config: ```nginx location / { try_files $uri $uri/ @backend; }

location @backend { # Named location doesn't inherit settings from parent proxy_pass http://localhost:3000; # Missing proxy_set_header Host $host; } ```

Solution: Configure named location fully: ``nginx location @backend { proxy_pass http://localhost:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }

Common Cause 3: Infinite Redirect Loop

Fallback URI triggers same location block recursively.

Problematic config: ``nginx location / { root /var/www/html; try_files $uri $uri/ $uri.html =404; }

1.If /about doesn't exist and /about/ doesn't exist:
2.Check /about.html - doesn't exist
3.Return 404

This works. But problematic:

nginx

location / {
    try_files $uri $uri/ /;  # / redirects back to this location
}

1.Request /missing:
2.Check /missing - no
3.Check /missing/ - no
4.Internal redirect to /
5./ matches same location
6.Check / - directory exists
7.Serve index

Worse - actual loop: ```nginx location / { try_files $uri $uri.html /index.html; }

location = /index.html { try_files $uri $uri/ /; # / triggers location / # Loop! } ```

Solution: Ensure fallback doesn't trigger same logic: ``nginx location / { try_files $uri $uri/ =404; # End with 404, not redirect }

Or use named location: ```nginx location / { try_files $uri $uri/ @fallback; }

location @fallback { proxy_pass http://backend; } ```

Common Cause 4: Try_Files with Alias

try_files uses $uri which doesn't account for alias mapping.

Problematic config: ``nginx location /assets/ { alias /var/www/files/; try_files $uri $uri/ =404; }

Request /assets/logo.png: - try_files checks /assets/logo.png using $uri - But file is at /var/www/files/logo.png (alias maps this) - $uri path doesn't match alias path

**Solution: Use $request_filename or adjust logic:** ``nginx location /assets/ { alias /var/www/files/; try_files $request_filename =404; }

$request_filename reflects the actual file path after alias mapping.

Or simpler - alias handles files directly: ``nginx location /assets/ { alias /var/www/files/; # Don't need try_files - alias handles file resolution }

Common Cause 5: Try_Files Ignoring Index Files

Directory fallback doesn't serve index files automatically.

Problematic config: ``nginx location / { root /var/www/html; try_files $uri $uri/ =404; }

1.Request /docs/ (directory exists):
2.$uri = /docs/
3.Check /docs/ - is directory? Yes
4.Nginx needs to serve directory index
5.But no index directive set!

Solution: Add index directive: ``nginx location / { root /var/www/html; index index.html index.htm; try_files $uri $uri/ =404; }

Now /docs/ serves /docs/index.html.

Common Cause 6: SPA Routing with API Conflicts

Single-page apps need all routes to hit index.html, but API routes need to bypass.

Problematic config: ```nginx location / { try_files $uri $uri/ /index.html; }

location /api/ { proxy_pass http://backend; } ```

This works, but /api/users hits /api location first.

Problem: ```nginx location / { try_files $uri $uri/ /index.html; }

# API location missing - all /api requests go to index.html ```

Solution: Define API location with priority: ```nginx location ^~ /api/ { proxy_pass http://backend; }

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

^~ ensures /api prefix stops further location searching.

Common Cause 7: Try_Files with Rewrite

Rewrite changes $uri before try_files evaluates.

Problematic config: ``nginx location / { rewrite ^/old/(.*)$ /new/$1 break; try_files $uri $uri/ =404; }

1.Request /old/page:
2.Rewrite changes $uri to /new/page
3.try_files checks /new/page
4.Works correctly

But with last: ``nginx location / { rewrite ^/old/(.*)$ /new/$1 last; # restarts location matching try_files $uri $uri/ =404; }

Rewrite with last restarts location matching - try_files may not be reached.

Common Cause 8: Try_Files Not Serving Actual File

File exists but 404 returned anyway.

Diagnosis: ```bash # Check if file exists ls -la /var/www/html/about

# Check Nginx error log tail -f /var/log/nginx/error.log ```

Common cause: Permission denied: ``nginx location / { root /var/www/html; try_files $uri $uri/ =404; }

File /var/www/html/about exists, but www-data can't read it.

bash

# Check permissions
ls -la /var/www/html/about
sudo -u www-data cat /var/www/html/about

Solution: Fix permissions: ``bash chmod 644 /var/www/html/about chown www-data:www-data /var/www/html/about

Common Cause 9: Static Files Going to Backend

All requests, including static files, hit the fallback.

Problematic config: ```nginx location / { try_files $uri @backend; # Missing $uri/ for directories }

location @backend { proxy_pass http://backend; } ```

Directories (like /css/) don't exist as files, go directly to backend.

Solution: Include directory check: ```nginx location / { root /var/www/html; try_files $uri $uri/ @backend; }

location @backend { proxy_pass http://backend; } ```

Verification

1.Test file resolution:
2.```bash
3.curl -I http://localhost/about
4.curl -I http://localhost/about/
5.curl -I http://localhost/missing
6.`
7.Add diagnostic headers:
8.```nginx
9.location / {
10.root /var/www/html;
11.try_files $uri $uri/ @fallback;

add_header X-Checked-Path $request_filename always; }

location @fallback { add_header X-Fallback "triggered" always; return 200 "fallback"; } ```

1.Check file existence:
2.```bash
3.ls -la /var/www/html/$uri
4.`
5.Monitor error log:
6.```bash
7.tail -f /var/log/nginx/error.log | grep "open()"
8.`
9.Debug internal redirects:
10.```nginx
11.error_log /var/log/nginx/debug.log debug;
12.`

Complete Working Configurations

Static site with fallback: ``nginx location / { root /var/www/html; index index.html; try_files $uri $uri/ $uri.html =404; }

Single-page application: ```nginx # API routes first location ^~ /api/ { proxy_pass http://backend; }

# Static assets location ^~ /static/ { root /var/www/html; expires 1y; }

# SPA fallback location / { root /var/www/html; try_files $uri $uri/ /index.html; } ```

With named location fallback: ```nginx location / { root /var/www/html; index index.html; try_files $uri $uri/ @backend; }

location @backend { proxy_pass http://localhost:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } ```

Verification

Issue	Cause	Fix
All requests go to fallback	Wrong argument order	Put `$uri` first
404 on existing files	Permission denied	Fix file permissions
Infinite redirect loop	Fallback triggers same location	Use named location
Alias doesn't work	`$uri` doesn't match alias path	Use `$request_filename`
Directories return 404	No index directive	Add `index index.html`
API goes to SPA fallback	Location priority	Use `^~` for API
Named location incomplete	Missing proxy headers	Configure named location fully

try_files requires understanding the argument sequence, fallback behavior, and interaction with other directives. Check order first, then verify permissions and path resolution.

[Nginx troubleshooting: Fix Lambda Permission Denied - Complete ](fix-lambda-permission-denied)
[Nginx web server troubleshooting: Fix Client Max Body Size Large Upload Nginx Issue ](client-max-body-size-large-upload-nginx)
[Fix Apache 502 Proxy Error](fix-apache-502-proxy-error)
[Fix Apache LogLevel Core Debug Configuration](fix-apache-loglevel-core-debug)
[Fix Cloudflare 502 Bad Gateway Error](fix-cloudflare-502-bad-gateway)

Was this guide helpful?

Related search paths

People also search for

If the symptom is close but not identical, these search paths usually surface the right neighboring fixes faster than scrolling the full archive.

Nginx try_files $request_filename Not Working - 404 and Fallback Errors Nginx try_files $request_filename Not Working - 404 and Fallback Errors Nginx Nginx try_files $request_filename Not Working - 404 and Fallback Errors troubleshooting Nginx try_files $request_filename Not Working - 404 and Fallback Errors fix Resolve Nginx `try_files $request_filename` returning 404 errors, fallback not working, and SPA routing failures with correct path and alias configuration Nginx Resolve Nginx `try_files $request_filename` returning 404 errors, fallback not working, and SPA routing failures with correct path and alias configuration

Explore Related Topics

Browse Guides from Other Categories

Discover troubleshooting guides from related categories to expand your knowledge.

FAQ

Nginx Troubleshooting FAQs

Common questions about troubleshooting and preventing similar issues

How do I know if this nginx-errors troubleshooting guide applies to my situation?

This guide is designed for nginx-errors issues. If you're experiencing similar symptoms described in the article, follow the step-by-step instructions. Start with the most common causes and work through the diagnostic process.

Is it safe to follow these nginx-errors troubleshooting steps?

Yes, all steps are designed to be safe and non-destructive. We recommend creating backups before making significant changes and testing each step before proceeding to the next.

How long does it typically take to resolve this type of nginx-errors issue?

Most nginx-errors issues can be resolved within 30 minutes to 2 hours, depending on the complexity and root cause. Follow the troubleshooting flow to identify and fix the problem efficiently.

How can I prevent this nginx-errors issue from happening again?

Regular maintenance, monitoring, and following best practices for nginx-errors configuration can help prevent recurrence. Consider implementing automated checks and alerts for early detection.

Written by

FixWikiHub Editorial Team

Our editorial team consists of experienced DevOps engineers, systems administrators, and cloud architects with hands-on experience in production environments across AWS, Azure, GCP, and on-premises infrastructure.

Every guide undergoes technical review for accuracy and is updated when software versions, commands, or best practices change.

Last updated: Nov 28, 2025

About our team

Important Notice

Disclaimer & Safety Guidelines

The troubleshooting steps in this guide are provided for educational and informational purposes. Before applying any changes to production systems:

Test in a staging environment first — Always verify commands and configurations in a non-production environment before deploying to live systems.
Create backups — Ensure you have current backups of databases, configurations, and critical files before making changes.
Understand the impact — Review how each step may affect your specific environment, dependencies, and users.
Consult official documentation — This guide supplements, but does not replace, official vendor documentation and best practices.

FixWikiHub is not responsible for any damages arising from the use of this content. See our Terms of Use for more information.

Resources

Official Documentation & Further Reading

For authoritative information, consult the official documentation for the technologies discussed in this guide. Our troubleshooting content supplements, but does not replace, vendor documentation.

AWS Documentation — Official Amazon Web Services guides and API references
Kubernetes Documentation — Official Kubernetes documentation
Nginx Documentation — Official Nginx web server documentation
Apache Documentation — Official Apache HTTP Server documentation
Docker Documentation — Official Docker container documentation

Fix Nginx try_files $request_filename Not Working - 404 and Fallback Errors

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Understanding Try_Files Behavior

Common Cause 1: Order of Arguments Matters

Common Cause 2: Named Location vs URI Fallback

Common Cause 3: Infinite Redirect Loop

Common Cause 4: Try_Files with Alias

Common Cause 5: Try_Files Ignoring Index Files

Common Cause 6: SPA Routing with API Conflicts

Common Cause 7: Try_Files with Rewrite

Common Cause 8: Try_Files Not Serving Actual File

Common Cause 9: Static Files Going to Backend

Verification

Complete Working Configurations

Verification

People also search for

Browse Guides from Other Categories

WordPress

SSL

DNS

Nginx Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading

Fix Nginx try_files $request_filename Not Working - 404 and Fallback Errors

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Understanding Try_Files Behavior

Common Cause 1: Order of Arguments Matters

Common Cause 2: Named Location vs URI Fallback

Common Cause 3: Infinite Redirect Loop

Common Cause 4: Try_Files with Alias

Common Cause 5: Try_Files Ignoring Index Files

Common Cause 6: SPA Routing with API Conflicts

Common Cause 7: Try_Files with Rewrite

Common Cause 8: Try_Files Not Serving Actual File

Common Cause 9: Static Files Going to Backend

Verification

Complete Working Configurations

Verification

Related Articles

People also search for

Share this guide

More Nginx Troubleshooting Guides

Browse Guides from Other Categories

Nginx Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading