Fixing nginx: [emerg] host not found in upstream Using Docker DNS Resolver 127.0.0.11
Solve nginx: [emerg] host not found in upstream in Docker Compose and Swarm. Configure Docker's internal DNS resolver 127.0.0.11 with dynamic set $upstream variables so Nginx boots and survives container restarts.
By default, Nginx resolves every hostname written inside an `upstream {}` block or a static `proxy_pass http://app:3000;` directive ONCE at startup using the system `/etc/resolv.conf`, and permanently caches that IP address for the lifetime of the master process. If the `app` container is not running yet when Nginx boots, Nginx crashes immediately with `nginx: [emerg] host not found in upstream`. Furthermore, if `app` is recreated later with a new Docker bridge IP, Nginx continues routing to the dead IP (returning 502 Bad Gateway). Fix both issues permanently by adding `resolver 127.0.0.11 valid=10s ipv6=off;` and assigning the upstream hostname to a runtime Nginx variable (`set $upstream http://app:3000; proxy_pass $upstream;`).
Verified Root Causes in Production Environments
- Static Boot-Time DNS Resolution in Nginx Open Source: Literal hostnames in `proxy_pass http://web:3000` or `upstream backend { server web:3000; }` are resolved synchronously during configuration parsing before worker processes even start.
- Stale Container IP Caching After Redeployments: Even if `depends_on` lets Nginx start after `web`, running `docker compose up -d --build web` assigns a brand-new `172.18.0.x` IP to `web`, while Nginx keeps forwarding traffic to the old container IP.
- Default Bridge Network Lacks Embedded DNS: Using the legacy default `bridge` network instead of a user-defined Docker Compose network disables the `127.0.0.11` internal DNS server.
1. How Docker's Embedded DNS Server (127.0.0.11) Works With Nginx Variables
Every container attached to a user-defined Docker Compose network has `/etc/resolv.conf` pointed to `nameserver 127.0.0.11`, which is the Docker daemon's built-in service discovery DNS resolver. However, Nginx Open Source only queries a custom `resolver` directive dynamically at request time when the target hostname inside `proxy_pass` contains an Nginx variable (such as `$upstream_app`).
When you replace a hardcoded `proxy_pass http://nextjs-app:3000;` with `resolver 127.0.0.11 valid=10s ipv6=off;` followed by `set $upstream_app http://nextjs-app:3000; proxy_pass $upstream_app;`, two critical behaviours change: (1) Nginx no longer checks if `nextjs-app` exists in DNS at startup, so the Nginx container boots cleanly even if the backend container is down, and (2) Nginx re-queries `127.0.0.11` every 10 seconds (`valid=10s`), automatically picking up new container IP addresses during rolling redeployments.
server {
listen 80;
server_name vexlo.cloud www.vexlo.cloud;
# 1. Declare Docker's internal embedded DNS server (127.0.0.11)
# valid=10s forces Nginx to refresh container IPs every 10 seconds after redeploys
resolver 127.0.0.11 valid=10s ipv6=off;
resolver_timeout 5s;
location / {
# 2. Store the upstream service name in a variable to force runtime DNS lookup
set $backend_upstream "http://nextjs-app:3000";
proxy_pass $backend_upstream;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
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;
}
}2. Critical Gotcha: URI Path Stripping When Using Variables in proxy_pass
There is a subtle Nginx URI-rewriting rule that trips up senior engineers when switching `proxy_pass` from a static string to a variable. In standard Nginx, writing `location /api/ { proxy_pass http://backend:4000/; }` strips the `/api/` prefix before forwarding the request. However, when `proxy_pass` uses a variable (`proxy_pass $api_upstream;`), Nginx passes the full original `$request_uri` unchanged unless you explicitly capture and append the regex path inside the variable.
Below is the exact pattern for both root proxying (preserving `$request_uri`) and prefix-stripping sub-path proxying (`/api/v1/*` forwarded as `/*`) using `127.0.0.11`.
server {
listen 80;
resolver 127.0.0.11 valid=10s ipv6=off;
# Pattern A: Pass full URI unchanged to upstream
location / {
set $web_upstream "http://frontend:3000";
proxy_pass $web_upstream;
}
# Pattern B: Strip '/api/' prefix when using a variable in proxy_pass
location ~ ^/api/(.*)$ {
set $api_upstream "http://api-service:4000";
# Explicitly append captured group $1 and query args $is_args$args
proxy_pass $api_upstream/$1$is_args$args;
proxy_set_header Host $host;
}
}3. Complete Docker Compose Configuration With Shared Bridge Network
Remember that `127.0.0.11` is only injected into containers that use a Docker Compose network (either the default network created by `docker compose up` or an explicit custom network). If you launch containers manually via `docker run` without `--network`, `127.0.0.11` will not exist. Always declare an explicit bridge network in `docker-compose.yml`.
services:
nginx:
image: nginx:1.27-alpine
restart: always
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/conf.d:/etc/nginx/conf.d:ro
networks:
- app-net
nextjs-app:
build: .
restart: unless-stopped
expose:
- "3000"
networks:
- app-net
networks:
app-net:
driver: bridgePre-Deployment Verification Checklist
- Add resolver 127.0.0.11 valid=10s ipv6=off; inside your Nginx server {} or http {} block.
- Replace static proxy_pass http://service:port; with set $upstream http://service:port; proxy_pass $upstream;.
- Remove static upstream {} blocks that reference container names unless using nginx:1.27.3+ with the resolve parameter.
- Verify both Nginx and your upstream container are attached to the same Docker Compose bridge network.
Deploy on Vexlo Cloud in 60s (₹149/mo UPI)
Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.
Frequently Asked Questions
Why does Nginx still return 502 Bad Gateway after I restart my Node.js container?
When you recreate or restart a container, Docker assigns it a new internal IP (e.g., changing from 172.18.0.3 to 172.18.0.5). Without `resolver 127.0.0.11 valid=10s` and a `$variable` in `proxy_pass`, Nginx caches 172.18.0.3 forever until you reload Nginx.
Can I use the resolve keyword inside an upstream {} block in free Nginx Open Source?
Historically, `server app:3000 resolve;` inside an `upstream` block was exclusive to Nginx Plus, though Nginx Open Source 1.27.3+ recently added native `resolve` support in `upstream` blocks (requiring `resolver 127.0.0.11;` and `zone`). The `set $upstream` variable method works universally across all Nginx versions.
Why should I include ipv6=off in the Docker Nginx resolver directive?
Standard Docker bridge networks are IPv4-only by default. Without `ipv6=off`, Nginx attempts AAAA IPv6 lookups alongside A lookups, causing unnecessary DNS latency and log warnings.