nginx: [emerg] host not found in upstream means nginx looked up the backend name in your proxy_pass or upstream block while it was starting, got no address back, and refused to start. In Docker this nearly always means one of three things: the two containers are not on the same user-defined network, the name is wrong, or the backend container was not running at the moment nginx started.
Nginx resolves those names once, when it loads its configuration, and then keeps the IP addresses. The fixes below go from "put both containers on one network" to letting nginx look names up again while it runs, through Docker's DNS server at 127.0.0.11. We reproduced every error line on a Debian 13 server with Docker on 19 November 2026, the same kind of setup you get on a KVM VPS or VDS from RS Computers in Amsterdam, Dublin or Prishtina.
Key facts, checked on 19 November 2026:
- Containers on Docker's default bridge network "cannot refer to each other by name"; containers on a custom network use Docker's embedded DNS server, whose address "is
127.0.0.11" (Docker networking overview). - When
proxy_passcontains a variable, nginx resolves a domain name "using a resolver" at request time instead of at startup (nginx proxy module). - The
resolveparameter forserverlines insideupstreamis free in nginx since 1.27.3, released 26 November 2024; before that it was part of the commercial subscription (nginx CHANGES, upstream module). - Debian 13 ships nginx 1.26.3, which rejects
resolvewithinvalid parameter "resolve". The officialnginx:1.30image (stable 1.30.7 today; mainline is 1.31.9, per nginx.org) accepts it. - With short
depends_on, Compose "does not wait for dependency services to be healthy";condition: service_healthymakes it wait (Compose file reference). - A host nginx cannot resolve container names at all. In our lab
getent hosts appon the host returned nothing while the container ran.
Quick fix
- Read the name in quotes in the error:
host not found in upstream "app". That exact name must be a Compose service name, a container name or a network alias on a network the nginx container is attached to.- Check it from inside nginx:
docker exec proxy getent hosts app. No output means nginx cannot resolve it either.- Not on a shared network?
docker network create appnet, then start both containers with--network appnet, or put both in onecompose.yaml.- Backend sometimes not up yet? Add a healthcheck and
depends_on: {web: {condition: service_healthy}}.- Nginx must start even when the backend is down, or the backend's IP changes? Add
resolver 127.0.0.11 valid=10s;and put the name in a variable:set $upstream_app app; proxy_pass http://$upstream_app:8000;.- Nginx installed on the host, app in a container? Do not use the container name; publish a port (
-p 127.0.0.1:8001:8000) and useproxy_pass http://127.0.0.1:8001;.
Error line, cause and fix
Every line in this table came out of our lab. The name in quotes and the line number will be yours.
| Error line | Cause | Fix |
|---|---|---|
[emerg] host not found in upstream "app" in /etc/nginx/conf.d/default.conf:3 | Name in proxy_pass did not resolve at startup: default bridge, wrong name, backend stopped, or nginx on the host | Same network, healthcheck, published port |
[emerg] host not found in upstream "app:8000" | Same thing for a server line inside an upstream block (the port is printed too) | Same as above, or the resolve parameter |
[error] ... no resolver defined to resolve app | Variable in proxy_pass but no resolver line; every request is a 502 | Add resolver 127.0.0.11 |
[error] ... app could not be resolved (2: Server failure) or (3: Host not found) | Runtime lookup failed: backend not running yet, or the name does not exist | Start the backend; fix the name. Nginx keeps running and recovers by itself |
[error] ... no live upstreams while connecting to upstream | With resolve, the name has no address yet, so the group is empty | Start the backend; lower resolver_timeout to retry sooner |
connect() failed (111: Connection refused) or (113: No route to host) with an old IP in upstream: | Container was recreated or stopped; nginx still uses the IP it resolved at start | nginx -s reload now; resolver + variable or resolve for good |
[emerg] invalid parameter "resolve" | Nginx older than 1.27.3, such as Debian 13's 1.26.3 | Use the variable method, or the official image or nginx.org packages |
[emerg] resolving names at run time requires upstream "backend" ... to be in shared memory | resolve without a zone line | Add zone backend 64k; to the upstream |
[emerg] no resolver defined to resolve names at run time in upstream "backend" | resolve without a resolver directive | Add resolver 127.0.0.11; in http or in the upstream |
A plain 502 with Connection refused and the right, current IP is a different problem, usually an app that listens on 127.0.0.1 inside its container. Our nginx 502 Bad Gateway guide covers that and nine other 502 causes.
How we tested
A fresh Debian 13 container on our lab host, with Debian's own packages: Docker 26.1.5, Docker Compose 2.26.1 and nginx 1.26.3 for the host tests. The proxy ran as the official nginx:1.30 image (nginx 1.30.7), the backend as python:3.13-slim running python -m http.server 8000. Each config below was started, requested with curl and read back with docker logs. Lab times are UTC.
Why nginx resolves upstream names only once
With a fixed name such as proxy_pass http://app:8000;, nginx turns app into IP addresses while it reads the configuration, using the system resolver from /etc/resolv.conf. If the lookup fails, nginx exits with [emerg]. If it works, nginx keeps those addresses until the next reload. A resolver line does not change this; nginx only uses it for names it looks up while running.
Keeping the addresses causes the quieter failure. Docker's Compose documentation says a recreated container "joins the network under a different IP address but the same name" (Compose networking). Our nginx had resolved app to 172.18.0.2. We recreated the app, it came back as 172.18.0.4, another container took the old address, and nginx went on sending traffic there:
[error] 23#23: *3 connect() failed (111: Connection refused) while connecting to upstream, client: 172.18.0.1, server: , request: "GET / HTTP/1.1", upstream: "http://172.18.0.2:8000/", host: "127.0.0.1:8080"
After docker exec proxy nginx -s reload the same request returned 200. In a Compose project where we only stopped the backend, the error read connect() failed (113: No route to host). Either way, the clue is an upstream: IP that no longer belongs to your app.
Fix 1: one user-defined network, and the right name
This fixes most cases. We started the app and an nginx container on Docker's default bridge, with this site config:
server {
listen 80;
location / { proxy_pass http://app:8000; }
}
The app was running, yet nginx exited with code 1 after 10.4 seconds, the time the failed lookup took on our network:
[emerg] 1#1: host not found in upstream "app" in /etc/nginx/conf.d/default.conf:3
nginx: [emerg] host not found in upstream "app" in /etc/nginx/conf.d/default.conf:3
On the default bridge, Docker copies the host's DNS settings into the container, and the host knows nothing about container names. On a network you create yourself, /etc/resolv.conf inside the container says nameserver 127.0.0.11, Docker's embedded DNS server, which answers with container names. So:
docker network create labnet
docker run -d --name app --network labnet python:3.13-slim python -m http.server 8000
docker run -d --name proxy --network labnet -p 8080:80 -v /lab/static.conf:/etc/nginx/conf.d/default.conf:ro nginx:1.30
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/
Here /lab/static.conf is the site config above; use your own path.
200
Order still matters. With the proxy started first on the same network, before the app existed, we got the same [emerg] line; started second, it worked.
Compose service name vs container_name
Docker Compose creates a network called <project>_default for every project and attaches all services to it, so you rarely need docker network create. We asked Docker's DNS from the proxy container in a project called shop with a service called web:
docker compose exec proxy sh -c 'for n in web shop-web-1 web.shop_default nosuch; do getent hosts $n || echo "$n: not found"; done'
172.20.0.2 web
172.20.0.2 shop-web-1
172.20.0.2 web.shop_default
nosuch: not found
The service name, the generated container name and the name with the network suffix all work. Use the service name: it stays the same when Compose recreates or renames containers, and the Compose documentation says "you should always reference services by name". A container_name: line adds one more name, but it also stops Compose from scaling the service past one container. If nginx and the app live in two different Compose projects, they are on two different networks, and neither name works until you attach both to one shared network, declared as external: true in the second project (Compose networking).
Fix 2: depends_on with a healthcheck
Compose starts services in dependency order, but a short depends_on: [web] only waits for the container to start, not for it to work. We gave web a command that exits at once with code 1 and the proxy restart: unless-stopped. Twelve seconds later the web container had exited, and nginx had already failed four times in a restart loop:
proxy: Up Less than a second
web: Exited (1) 12 seconds ago
proxy-1 | nginx: [emerg] host not found in upstream "web" in /etc/nginx/conf.d/default.conf:3
Docker's DNS only answers for running containers, so a crashed backend takes nginx down with it. A healthcheck makes Compose wait until the backend really answers. This is the file we ran, with a backend that needs 5 seconds to come up:
services:
web:
image: python:3.13-slim
command: sh -c "sleep 5; python -m http.server 8000"
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/')"]
interval: 5s
timeout: 3s
retries: 5
start_period: 10s
start_interval: 1s
proxy:
image: nginx:1.30
ports: ["8080:80"]
volumes: ["./nginx.conf:/etc/nginx/conf.d/default.conf:ro"]
depends_on:
web:
condition: service_healthy
restart: unless-stopped
Container shop-web-1 Waiting
Container shop-web-1 Healthy
Container shop-proxy-1 Starting
Container shop-proxy-1 Started
docker compose up -d returned after 7 seconds and the first request was a 200. Use any check your image can run, such as curl -f or pg_isready; start_interval needs Docker Compose 2.20.2 or later.
This only covers startup. When we later stopped web and restarted only the proxy, nginx exited with the same [emerg]. If the backend can be down while nginx restarts, use one of the next two fixes.
Fix 3: resolver 127.0.0.11 and a variable in proxy_pass
This works in every nginx version. Put the backend name in a variable, and nginx stops looking it up at startup and asks the resolver when a request comes in:
server {
listen 80;
resolver 127.0.0.11 valid=10s ipv6=off;
resolver_timeout 5s;
location / {
set $upstream_app app;
proxy_pass http://$upstream_app:8000;
}
}
valid=10s overrides the TTL in DNS answers, so a new container IP is picked up within about 10 seconds. ipv6=off stops nginx asking for IPv6 addresses; our lab network was IPv4 only. Leave it out if your Docker network has IPv6.
We started this proxy with no app container at all. It came up, and requests failed one by one instead of the whole server failing:
[error] 21#21: *1 app could not be resolved (2: Server failure), client: 172.18.0.1, server: , request: "GET / HTTP/1.1", host: "127.0.0.1:8080"
That 502 took 3.7 seconds, because Docker's DNS passed the unknown name on to the host's DNS servers. For a name that does not exist anywhere, nginx answered at once with could not be resolved (3: Host not found). Once the app started, requests returned 200 within 2 seconds, with no reload. We then moved the app to a new IP: requests to the old address hung until our 4-second curl limit for two tries, and about 12 seconds after the switch every request was a 200 again, still without a reload.
Forget the resolver line and nginx starts happily, then fails every request:
[error] 20#20: *1 no resolver defined to resolve app, client: 172.18.0.1, server: , request: "GET / HTTP/1.1", host: "127.0.0.1:8080"
Two traps with the variable method
The path. With a variable, nginx no longer swaps the location prefix for the URI in proxy_pass; it sends that URI "as is, replacing the original request URI" (proxy_pass). With location /a/ { proxy_pass http://$upstream_app:8000/; }, our request for /a/etc/hostname reached the app as GET /. Leave the URI off and strip the prefix with a rewrite instead; this one arrived as GET /etc/hostname:
location /b/ {
set $upstream_app app;
rewrite ^/b/(.*)$ /$1 break;
proxy_pass http://$upstream_app:8000;
}
Fixed names still resolve at startup. The variable only helps in the lines that use it. A second proxy_pass http://app:8000; somewhere else in the config, or an upstream block with server app:8000;, still gives the startup [emerg].
Let the official image fill in the resolver
Hard-coding 127.0.0.11 is fine inside Docker, but the official image can read it from the container's own /etc/resolv.conf. Set NGINX_ENTRYPOINT_LOCAL_RESOLVERS=1, put your config in /etc/nginx/templates/default.conf.template with resolver ${NGINX_LOCAL_RESOLVERS} valid=10s;, and the entrypoint writes the real address into /etc/nginx/conf.d/default.conf (the image's 15-local-resolvers.envsh). In our lab the generated file read resolver 127.0.0.11 valid=10s ipv6=off; and the page returned 200.
Fix 4: the resolve parameter on upstream servers (nginx 1.27.3 and later)
If you want an upstream block, for load balancing or keepalive, nginx 1.27.3 and later can re-resolve its server names while running. The documentation says the parameter "monitors changes of the IP addresses that correspond to a domain name of the server" and that the group "must reside in the shared memory" (upstream module). This is the config we ran on nginx:1.30:
resolver 127.0.0.11 valid=10s ipv6=off;
resolver_timeout 5s;
upstream backend {
zone backend 64k;
server app:8000 resolve;
}
server {
listen 80;
location / { proxy_pass http://backend; }
}
With no app running, nginx -t passed and nginx started. Requests got a 502 with a new line, because the group had no addresses yet:
[error] 21#21: *2 no live upstreams while connecting to upstream, client: 172.30.0.1, server: , request: "GET / HTTP/1.1", upstream: "http://backend/", host: "127.0.0.1:8080"
Leave out zone or resolver and the test fails with the two [emerg] lines in the table above. Debian 13's nginx 1.26.3 refuses the parameter outright:
[emerg] 7069#7069: invalid parameter "resolve" in /etc/nginx/conf.d/resolve-test.conf:5
One thing we did not expect: without the resolver_timeout 5s; line, nginx needed 31 seconds to notice the app after it started; with it, 7 seconds. In nginx's source, a failed lookup other than "name does not exist" is retried after resolver_timeout, which defaults to 30 seconds (ngx_http_upstream_zone_module.c, resolver_timeout). Our failed lookups came back as "Server failure", so set the shorter timeout. After a move to a new IP, both this and the variable method were back to steady 200s in about 21 seconds.
| Nginx you run | Version (19 November 2026) | resolve in upstream? |
|---|---|---|
| Debian 13 package | 1.26.3 (lab) | No: use the variable method |
| Ubuntu 26.04 LTS package | 1.28.3 (packages.ubuntu.com) | Yes |
Official image nginx:1.30 | 1.30.7 stable (lab) | Yes, tested |
| nginx.org mainline | 1.31.9 (nginx.org) | Yes |
Check yours with nginx -v, or docker exec proxy nginx -v for a container.
Nginx on the host, app in a container
Here the container name never works, because the host does not use Docker's embedded DNS. With the app container running, Debian's own nginx refused the config:
[emerg] 9106#9106: host not found in upstream "app" in /etc/nginx/sites-enabled/hostproxy:3
nginx: configuration file /etc/nginx/nginx.conf test failed
The container IP from docker inspect is no answer either; it changes when the container is recreated. Publish the container port on the host's loopback address and point nginx there:
docker run -d --name app -p 127.0.0.1:8001:8000 python:3.13-slim python -m http.server 8000
location / { proxy_pass http://127.0.0.1:8001; }
sudo nginx -t && sudo systemctl reload nginx passed and the page returned 200. Binding to 127.0.0.1 keeps port 8001 off the internet, so nginx stays the only way in. If you now get a 502 with Connection reset by peer, the app inside listens on 127.0.0.1; the Docker section of our 502 guide shows that case. For certificates in front of all this, our reverse proxy and free HTTPS guide compares nginx with Caddy and Traefik.
Kubernetes and Docker Swarm, briefly
We did not test these in the lab. In Kubernetes, a normal Service name "resolves to the cluster IP of the Service", which stays put while pods change; a headless Service resolves to the pod IPs (Kubernetes DNS for Services and Pods). So there the startup error usually means a wrong name or namespace. In Swarm, each service gets a virtual IP by default; with --endpoint-mode dnsrr the name returns task IPs, and the resolver fixes above apply (Swarm networking).
Frequently asked questions
What does nginx: [emerg] host not found in upstream mean?
Nginx could not resolve the host name in a proxy_pass or upstream server line while loading its configuration, so it refused to start or reload. The name in quotes is the one that failed. In Docker it usually means the containers share no user-defined network, the name is misspelled, or the backend container was not running.
What is 127.0.0.11 in nginx configs?
It is the address of Docker's embedded DNS server, which containers on user-defined networks use to resolve each other's names. resolver 127.0.0.11; tells nginx to ask it at request time. It only works inside a container on such a network, not on the host and not on the default bridge.
Why does nginx start but return 502 with "no resolver defined to resolve"?
Your proxy_pass contains a variable, so nginx looks the name up per request, but no resolver directive tells it which DNS server to ask. Add resolver 127.0.0.11 valid=10s; in the server or http block and reload.
Should I use the Compose service name or container_name in proxy_pass?
The service name. Both resolve on the project's network, as our lab showed, but the service name survives container recreation and scaling, while container_name blocks scaling beyond one container.
Does depends_on fix host not found in upstream?
Only partly. Short depends_on waits for the container to start, not to be healthy, and does nothing when the backend dies later. Use condition: service_healthy with a healthcheck for startup, and a resolver with a variable or the resolve parameter if nginx must survive a backend that is down.
Can I use the resolve parameter on Debian 13?
Not with Debian's nginx 1.26.3; it fails with invalid parameter "resolve". The parameter needs nginx 1.27.3 or later, such as the official nginx:1.30 image or Ubuntu 26.04's 1.28.3. On Debian 13's package, use the variable method.
Need a hand?
Most of these errors disappear once nginx and the app share one Compose network and nginx uses the service name; the resolver and resolve fixes are for setups where containers come and go. If your stack has outgrown a small server, or you want the whole thing on a fresh machine, you can move to a VPS or a VDS with dedicated vCPUs with NVMe in Amsterdam, Dublin or Prishtina, with full root access for Docker. If you would rather not build it yourself, we do custom offers, custom setups and systems built for you, Docker and reverse proxy stacks included, quoted per job: write to us on Telegram or by email at info@rscomputers-ks.com. Prefer a panel that writes the proxy config for you? Our Coolify vs Dokploy comparison shows what each one sets up, and the guide to running Docker on a VPS covers the basics.