NGINX location & Regex Precedence Prompt
Figure out exactly which location block NGINX picks for a given request and fix the ordering bug that's routing your URL to the wrong handler — with the matching rules made explicit, not folklore.
- Target user
- Engineers debugging why a URL hits the wrong location, 404s, or skips a handler
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior NGINX engineer who knows the location matching algorithm cold: exact `=`, then prefix `^~`, then regex `~`/`~*` in file order, then the longest plain prefix as a fallback. You explain precedence by tracing a concrete request, not by quoting docs. I will provide: - The full set of `location` blocks in conflict: [PASTE LOCATION BLOCKS] - The request path(s) that go to the wrong place: [PASTE URLS] - What I expected each URL to match, and what it actually matches: [DESCRIBE EXPECTED VS ACTUAL] Do this: 1. **Trace the algorithm** for each problem URL: which modifiers exist (`=`, `^~`, `~`, `~*`, plain prefix), the order NGINX evaluates them, and the exact block that wins. State the rule that decided it. 2. **Explain the trap** if present: a regex block stealing traffic from a prefix because no `^~` short-circuits it; file-order dependence among regex blocks; a missing `=` for a hot exact path; or `try_files` inside the wrong block. 3. **Rewrite the blocks** so each URL lands where intended. Use `^~` to stop regex evaluation for a prefix, `=` for single hot paths (e.g. `/`), and order regex blocks deliberately since they match top-to-bottom. 4. **try_files / rewrite interaction** — if `try_files` or `rewrite` is involved, show how the rewritten URI re-enters location matching (or doesn't, with `last` vs `break`). 5. **Prove it** — give a small table mapping each test URL to the block it will match after the fix, and `curl` commands that exercise each path. Output: (a) a per-URL trace of the current (broken) match, (b) the corrected `location` blocks with comments on each modifier choice, (c) the URL→block proof table, (d) the curl test commands. Validate the corrected config with `nginx -t` and reload; do not hot-edit the live config.
Why this prompt works
NGINX location precedence is one of the most misremembered topics in web ops because the order you write blocks is not the order NGINX evaluates them — exact and ^~ prefix matches short-circuit before any regex runs, but plain prefixes are a fallback after regex. The prompt forces a per-URL trace through the real algorithm, so the answer explains why a block wins rather than just asserting it.
By naming the specific traps — a greedy regex stealing a prefix, file-order dependence among regex blocks, a missing = on a hot path — the model produces a fix targeted at your actual bug instead of a generic reordering.
The URL→block proof table plus curl commands make the result verifiable. You confirm every path lands where intended, and you gate the change behind nginx -t so a reorder that accidentally exposes a sensitive path never reaches production silently.