NGINX proxy_pass: URI Rewriting, Variables, and DNS Gotchas

NGINX proxy_pass looks like the simplest directive in the entire configuration language: point it at a backend and requests flow through. Yet it is responsible for more production incidents than almost any other line in nginx.conf, because it hides two sharp edges. The first silently rewrites request URIs depending on a single trailing slash. The second is DNS: NGINX resolves a proxy_pass hostname once, when the configuration is loaded, and never re-resolves it, so when the backend’s IP address changes, NGINX keeps sending traffic to the stale address until you reload it or enable a re-resolving mechanism: the resolve parameter available since NGINX 1.27.3, or the nginx-module-upstream-jdomain package.

This guide covers the proxy_pass directive itself: its three forms, the exact URI rewriting rules, variables and runtime resolution, where the directive is allowed, and how to fix the frozen-DNS problem properly. For the broader picture (buffering, WebSockets, SSL termination), see our NGINX reverse proxy pillar guide.

The three forms of proxy_pass

The NGINX proxy_pass directive accepts an address in one of three forms:

location /app/ {
    # 1. An upstream block name
    proxy_pass http://backend_pool;
}

location /api/ {
    # 2. A hostname or IP address, with optional port
    proxy_pass http://127.0.0.1:8081;
}

location /socket/ {
    # 3. A UNIX domain socket
    proxy_pass http://unix:/run/app.sock;
}

The first form refers to an upstream {} block, which unlocks load balancing, keepalive connection pooling, and failure handling. The second and third are direct addresses. An important precedence rule applies to literal values: if an upstream {} block and a real DNS name share the same name, the upstream block wins, because NGINX looks the name up among configured upstream groups at configuration load and only falls back to DNS when no group matches.

URI rewriting: the trailing slash that changes everything

Whether proxy_pass rewrites the request URI depends on whether its value carries a URI part (anything after the host and port, even a lone /):

• No URI part, as in proxy_pass pointing at 127.0.0.1:8081 with nothing after the port: the original request URI is passed to the backend unchanged.
• With a URI part, even a lone / after the port: the part of the request URI that matched the location prefix is cut off and replaced by the configured URI.

That single rule produces this behavior matrix, which we verified by running each combination against a backend that echoes the URI it receives. Each row uses proxy_pass pointing at 127.0.0.1:8081 plus the URI part shown:

Rows three and four are the classic traps. In row three, the location has no trailing slash, so only /app is stripped and the leftover /x is glued onto /, producing a double slash. In row four, the replacement URI /api has no trailing slash, so the leftover x is concatenated directly, producing /apix. The rule of thumb: keep location and the proxy_pass URI part consistent, and end both with a slash.

Using variables in proxy_pass

The moment a variable appears in proxy_pass, its behavior changes in two fundamental ways:

resolver 127.0.0.53 valid=30s;

location /dyn/ {
    set $backend "app.example.com";
    proxy_pass http://$backend:8081;
}

First, URI handling: with variables, NGINX cannot compute the prefix replacement at configuration time. If the value carries no URI, the original request URI is passed as-is; if you need rewriting, you must construct the URI explicitly by appending a variable such as $request_uri to the target.

Second, name resolution moves to request time. NGINX matches the evaluated value against configured upstream {} group names first, but the match is exact, and in our tests a variable target carrying an explicit port bypassed a same-named upstream group entirely and went straight to DNS. Do not count on variable-based proxy_pass reaching an upstream {} block; when it misses, the lookup goes through the resolver directive. Without a resolver defined, the request fails with HTTP 502 and the error log states plainly: no resolver defined to resolve app.example.com. The resolver directive is valid in http, server, and location blocks, and its valid= parameter overrides DNS TTLs.

This variable trick is a popular workaround for the frozen-DNS problem, because each resolution honors valid=. But it comes at a cost: a plain address in proxy_pass bypasses upstream {} features entirely, so you lose keepalive connection pooling, load balancing across multiple IPs, and per-server failure accounting. There is a better way, covered below.

Where proxy_pass is allowed

NGINX proxy_pass is valid in location blocks, if blocks inside a location, and limit_except blocks. Two restrictions matter in practice:

1. In a regex location, a named location, an if block, or a limit_except block, proxy_pass must not carry a URI part. NGINX refuses to start with: "proxy_pass" cannot have URI part in location given by regular expression, or inside named location, or inside "if" statement, or inside "limit_except" block. The reason follows from the rewriting rule: there is no fixed prefix to strip in a regex match.
2. If a rewrite changes the URI inside a location with a URI-carrying proxy_pass, the rewritten URI is used and the configured replacement URI is ignored.

# Valid: regex location, no URI part
location ~ ^/img/ {
    proxy_pass http://127.0.0.1:8081;
}

Passing the right headers

By default, NGINX sends the backend a Host header equal to the hostname from the proxy_pass value, not the one the client sent. For most applications you want to forward the original:

location /app/ {
    proxy_pass http://127.0.0.1:8081/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

proxy_set_header covers the common cases, but it cannot delete an arbitrary client header or rewrite response headers coming back from the backend. For that, the headers-more module (nginx-module-headers-more in our repository) adds more_set_input_headers for the request side and more_set_headers for the response side.

The frozen-DNS problem, solved properly

Here is the failure mode that pages people at 3 a.m. A proxy_pass pointing at a cloud load balancer, a container service, or any backend behind dynamic DNS works fine for weeks. Then the provider rotates the backend’s IP. Every other client notices within the DNS TTL; NGINX does not, because static hostnames in proxy_pass and upstream {} blocks are resolved exactly once, at startup or reload. The symptom is a sudden wall of 502/504 errors that a systemctl reload nginx magically fixes.

You have three escalating options.

Option 1: variables plus resolver

The workaround shown earlier. Simple, but you give up upstream {} features, and every uncached lookup adds latency to the request that triggers it.

Option 2: the stock resolve parameter (NGINX 1.27.3+)

Since NGINX 1.27.3, the previously commercial resolve parameter of the server directive is available in open source. It re-resolves upstream servers in the background, honoring TTLs, and requires a shared memory zone plus a resolver in the upstream block:

upstream app_backend {
    zone app_backend 64k;
    server app.example.com:8081 resolve;
    resolver 127.0.0.53 valid=30s;
}

This is the preferred solution on any current NGINX, and we covered it in depth in NGINX upstream resolve. We verified the configuration above, including a live DNS flip picked up in the background, on stock Rocky Linux 10 (NGINX 1.28.2). The catch: older distributions lag behind. Enterprise Linux 9 and Ubuntu 24.04 top out at NGINX 1.24, which lacks the feature. The fastest way to get it there is to install the latest stable NGINX from the GetPageSpeed repository, available for every supported distribution.

Option 3: the upstream-jdomain module

The stock resolve parameter is TTL-driven and requires a shared memory zone. When you want different semantics, the nginx-module-upstream-jdomain package provides the battle-tested jdomain directive: request-driven re-resolution on a fixed interval you control, no shared memory zone, and retention of the last known good addresses when DNS itself goes down. Because our modules are built against the current GetPageSpeed NGINX build, installing it also brings your NGINX up to the latest stable version in the same transaction. Mechanically, each request to the upstream checks whether the interval has elapsed; if so, it kicks off a non-blocking DNS query and swaps in the fresh address list on completion, so no request ever waits for DNS. In our test bench, a DNS record flip propagated to live traffic within seconds of the interval elapsing.

RHEL, CentOS, AlmaLinux, Rocky Linux

sudo dnf install https://extras.getpagespeed.com/release-latest.rpm
sudo dnf install nginx-module-upstream-jdomain

Then load the module at the top of nginx.conf:

load_module modules/ngx_http_upstream_jdomain_module.so;

Debian and Ubuntu

First, set up the GetPageSpeed APT repository, then install:

sudo apt-get update
sudo apt-get install nginx-module-upstream-jdomain

On Debian/Ubuntu, the package handles module loading automatically. No load_module directive is needed.

Configuration

resolver 127.0.0.53;

upstream app_backend {
    jdomain app.example.com port=8081 interval=10;
}

server {
    listen 80;
    location / {
        proxy_pass http://app_backend;
        proxy_set_header Host $host;
    }
}

The jdomain directive is valid only inside upstream {} blocks. Its parameters: port= (default 80), interval= in seconds (default 1), max_ips= caps how many resolved addresses are kept (default 4), ipver=4 or ipver=6 restricts the address family, and strict makes resolution failures mark the upstream down instead of reusing stale addresses. Because resolution is asynchronous, the module keeps serving the last known good addresses while a query is in flight, which is exactly the behavior you want during a DNS outage.

Two operational notes from our test bench. First, the initial resolution at startup is synchronous through the system resolver (/etc/resolv.conf), not the resolver directive; if the domain does not resolve at load time, NGINX refuses to start with host not found in upstream. Second, each worker process keeps its own re-resolution timer, so immediately after a DNS change different workers may briefly answer from different backends until each one passes its own interval.

The module pages list all supported distributions: RPM and APT.

Keepalive: the performance follow-up

Once proxy_pass targets an upstream {} block, enable connection reuse. Without it, NGINX opens and closes a TCP connection to the backend for every request:

upstream app_backend {
    server 127.0.0.1:8081;
    keepalive 16;
}

server {
    listen 80;
    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

Both extra directives are required: proxy_http_version 1.1 because keepalive needs HTTP/1.1, and clearing the Connection header because NGINX otherwise forwards Connection: close. This pairing works with jdomain too, giving you re-resolving DNS and pooled connections at the same time.

Troubleshooting

• 502 with no resolver defined to resolve ... in the error log: a variable-based proxy_pass (or jdomain) has no resolver configured in scope. Add one.
• "proxy_pass" cannot have URI part in location given by regular expression ... at startup: remove the URI part (including a bare trailing slash after the port) from proxy_pass inside regex locations, named locations, if, and limit_except blocks.
• Backend receives doubled or concatenated paths (//x, /apix): a location/proxy_pass trailing-slash mismatch; see the matrix above.
• 502/504 that a reload fixes: the frozen-DNS problem; apply one of the three options above.
• host not found in upstream ... at startup with jdomain: the domain must be resolvable through the system resolver when the configuration loads; fix /etc/resolv.conf or the record itself.
• Wrong virtual host served by the backend: the default Host header is the proxy_pass hostname; add proxy_set_header Host $host;.

For status-code-specific debugging, our NGINX 502 Bad Gateway guide walks the full checklist.

Conclusion

A correct proxy_pass setup only stays correct until someone touches the config. A trailing slash added during a refactor or an upstream moved behind dynamic DNS quietly reintroduces the exact failure modes this guide eliminates. GetPageSpeed Amplify runs scheduled gixy scans across every host and ties findings to live NGINX runtime metrics. Drop-in compatible with the deprecated nginx-amplify-agent (EOL January 2026).

NGINX proxy_pass rewrites URIs only when its value carries a URI part, resolves static hostnames only once, and gains both re-resolution and connection pooling when pointed at an upstream {} block with jdomain and keepalive. The jdomain module source lives at nicholaschiasson/ngx_upstream_jdomain; we package it, along with 140+ other production NGINX modules, in the GetPageSpeed Premium Repository, where every one of them is a single dnf install away.