How to Fix Nginx Location Block Priority Error

In this tutorial, you'll learn about How to Fix Nginx Location Block Priority Error. We cover key concepts, practical examples, and best practices.

Nginx serves the wrong content or returns 404 because a more general location block is matching instead of the intended specific one — location block priority rules are misunderstood.

The Problem

# Wrong: User expects /api/* to go to proxy, but static files are served
location /api {
    proxy_pass http://backend:3000;
}
# This matches /api AND /api2, /api3 etc.

Step-by-Step Fix

Step 1: Use exact match for specific paths

# Exact match: highest priority
location = /api {
    proxy_pass http://backend:3000;
}

# Prefix match: matches /api/anything
location /api/ {
    proxy_pass http://backend:3000;
}

Step 2: Understand priority order

# Priority 1: Exact match (=)
location = /exact { ... }

# Priority 2: Preferential prefix (^~)
location ^~ /api/ { ... }

# Priority 3: Regex match (~ or ~*)
location ~ ^/api/v[0-9]/ { ... }

# Priority 4: Regular prefix
location /api/ { ... }

Step 3: Use regex for pattern matching

# Case-sensitive regex
location ~ ^/api/(users|posts)/ {
    proxy_pass http://backend:3000;
}

# Case-insensitive regex
location ~* \.(jpg|jpeg|png)$ {
    root /var/www/images;
}

Step 4: Debug location matching

# Add debug logging
location / {
    access_log /var/log/nginx/debug.log;
    add_header X-Debug-Location $uri;
    try_files $uri $uri/ /index.html;
}

Prevention Tips

• Use location = /exact for fixed endpoints (highest priority)
• Use location ^~ /prefix/ to block regex processing
• Order regex locations by specificity (most specific first)
• Test location matching with curl -I and check response headers

Common Mistakes with location priority

1. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
2. Non-exhaustive pattern matches that compile with warnings then crash at runtime
3. Misunderstanding that String is [Char] with poor performance for large text operations

These mistakes appear frequently in real-world NGINX code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ