nginx proxy_pass URI simulator

The rule, in one sentence#

If proxy_pass contains a URI part, meaning anything after the host and optional port including a bare /, nginx replaces the portion of the request URI that matched the location with that URI. If proxy_pass has no URI part, the request URI is forwarded unchanged and nothing is stripped.

Everything people call "the trailing slash thing" follows from that one sentence. The simulator above applies it to your exact values and shows the resulting upstream request line.

The four cases people hit#

The third row is the one that produces a 404 nobody can explain. Many backends treat //v1/users as a different path from /v1/users, and some frameworks 301 it, which then breaks POST bodies.

What the simulator will not tell you#

• Location selection. It assumes the location you entered is the one nginx picks. Real selection runs exact = matches first, then the longest matching prefix, remembering ^~, then regular expressions in file order. If the wrong block is being used, the rewrite is not your problem.
• rewrite directives. A rewrite ... break; inside the location changes $uri before proxy_pass runs, and then the replacement uses the rewritten value.
• Normalisation. nginx decodes and normalises the URI into $uri before matching, collapsing .. and, by default, merging repeated slashes. $request_uri keeps the raw form. Which one reaches the upstream depends on whether a URI part is present.

When proxy_pass contains a variable#

Using a variable, for example proxy_pass http://$upstream;, changes three things at once, and the simulator flags all three:

1. No prefix replacement happens. The value is used exactly as written after substitution.
2. nginx resolves the host at request time, so a resolver directive must be in scope or the request fails with "no resolver defined to resolve ...".
3. A name that matches an upstream {} block is no longer looked up as an upstream group in the usual way, so load balancing and keepalive settings you configured there stop applying.

That combination is also the classic accidental open proxy, covered in open proxies and misconfigured relays.

Frequently asked questions#

Why does adding a trailing slash to proxy_pass change the URL?#

Because a trailing slash is a URI part. With proxy_pass http://backend/ nginx replaces the matched location prefix with /, stripping it. With proxy_pass http://backend there is no URI part, so the full request URI is passed through.

Why am I getting a double slash at the upstream?#

Your location does not end in a slash but your proxy_pass URI does, so the matched prefix /api is replaced by / and the remaining /v1/users is appended to it. Make the trailing slashes match on both sides.

Can I use proxy_pass with a URI inside a regex location?#

No. nginx refuses to start, because there is no literal prefix to replace. Use rewrite ^/api/(.*)$ /$1 break; before a proxy_pass with no URI part, or build the target URI explicitly.

Does the query string get rewritten too?#

No. $args is passed through untouched. Only the path portion participates in the prefix replacement.

Which Host header does the upstream see?#

By default nginx sends Host: $proxy_host, which is the host from proxy_pass, not the client's Host. If your backend does name based virtual hosting or builds absolute URLs, set proxy_set_header Host $host; explicitly. The consequences are covered in X-Real-IP, X-Forwarded-Proto, Host and Port.