nginx location tester

How nginx chooses a location

1. The URI is normalised first: percent-decoding, repeated slashes merged, . and .. resolved. The query string is never part of location matching.
2. All prefix locations (no modifier, =, ^~) are compared. An = exact match wins immediately. Otherwise the longest matching prefix is remembered.
3. If that longest prefix has ^~, it wins and regexes are skipped.
4. Regex locations (~ case-sensitive, ~* case-insensitive) are tested in the order they appear in the file. The first match wins, even if a longer prefix matched earlier.
5. If no regex matches, the remembered longest prefix is used.
6. Inside the winning location the same procedure runs again for nested locations.

Two consequences surprise people most: a plain location /images/ loses to location ~ \.png$ for /images/a.png, because regexes are checked after prefixes; and location /api also matches /apiary, because prefixes are string prefixes, not path segments. Use /api/ or ^~ when you mean it.

proxy_pass and the trailing slash

If proxy_pass has a URI part (anything after the host, even just /), nginx replaces the part of the request URI that matched the location prefix with it. location /api/ { proxy_pass http://app/; } turns /api/users into /users. Without a URI part, the request URI goes through unchanged. Mismatched slashes (/api vs /api/, or http://app vs http://app/) produce //users or users — the tester prints the exact upstream URI so you can see it. A URI part is not allowed in a regex location unless a rewrite changed the URI first.

root vs alias

root appends the whole URI to the directory: root /srv; location /static/ serves /srv/static/x.css. alias replaces the location prefix: alias /srv/assets/; location /static/ serves /srv/assets/x.css. With alias the trailing slashes of the location and the alias must agree, and in a regex location alias must use captures.

rewrite flags

try_files

Each argument is checked as a file (or directory, with a trailing slash) relative to root/alias; the first that exists is served. The last argument is the fallback and is not checked: it is an internal redirect to a URI (which goes through location matching again), a named location @name, or =404-style status code. The tester cannot see your filesystem, so it lists the paths that would be checked.

add_header inheritance

add_header is inherited from the server level only when the location has no add_header of its own. One add_header Cache-Control in a location silently drops the security headers set at server level. The trace flags this.

Questions