You know that feeling when something works fine, then you change one line and everything breaks? That happened to me last week with nginx.
I had a simple reverse proxy config:
location /api {
proxy_pass http://backend-service;
}
Worked great. Then I needed to make the upstream dynamic based on a header, so I changed it to:
location /api {
set $upstream http://$http_x_backend_host;
proxy_pass $upstream;
}
Suddenly, nginx wouldn't reload. The error log said "no resolver defined to resolve backend-service."
What Changed
When you use a variable in proxy_pass, nginx switches from using the system resolver at startup to runtime DNS resolution. That means it needs a resolver directive to know which DNS server to query.
Without it, nginx has no idea how to look up hostnames on the fly.
The Fix
Add a resolver directive pointing to your DNS server:
location /api {
resolver 127.0.0.11 valid=10s;
set $upstream http://$http_x_backend_host;
proxy_pass $upstream;
}
If you're running in Docker, 127.0.0.11 is the embedded DNS server. On a regular system, you might use 8.8.8.8 or your internal DNS.
The valid=10s part controls how long nginx caches the DNS result. Without it, nginx uses the TTL from the DNS response, which might be way too long for your comfort.
Why This Matters
The resolver directive does more than just make variables work. It controls DNS caching behavior for your entire location block.
Say your backend service moves to a new IP. Without valid=10s, nginx might cache the old IP for hours (or forever, depending on your DNS setup). With it, you get fresh lookups every 10 seconds.
Debugging DNS Issues
When things aren't resolving right, strace is your friend:
strace -e trace=network -p $(pgrep nginx)
You'll see the actual DNS queries nginx is making. If you see nothing, your resolver directive is missing or wrong.
Another quick check:
nginx -T | grep resolver
Shows you all resolver directives across your config. Handy when you have multiple location blocks and aren't sure which one is missing it.
The Gotcha
Here's what caught me: the resolver directive is per-location, not global. If you put it in the http block, your location blocks still need their own resolver if they use variables.
Also, if you're using upstream blocks (the ones without variables), you don't need resolver at all. nginx resolves those at startup and caches them. It's only when you introduce variables that runtime resolution kicks in.
When to Use This
Dynamic backends based on headers, query params, or cookies. Multi-tenant setups where different customers hit different upstreams. A/B testing where you route to different services based on a flag.
For most static reverse proxy configs, you don't need this. But the moment you want runtime flexibility, you need the resolver directive.
Keep it simple. Add the resolver, set a reasonable cache time, and you're done.
Top comments (0)