← Back to Blog

nginx: [emerg] Host Not Found in Upstream in Docker: Causes and Tested Fixes

Published · by Leo Gashi, RS Computers

Nginx Docker Troubleshooting

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:

Quick fix

  1. 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.
  2. Check it from inside nginx: docker exec proxy getent hosts app. No output means nginx cannot resolve it either.
  3. Not on a shared network? docker network create appnet, then start both containers with --network appnet, or put both in one compose.yaml.
  4. Backend sometimes not up yet? Add a healthcheck and depends_on: {web: {condition: service_healthy}}.
  5. 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;.
  6. 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 use proxy_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 lineCauseFix
[emerg] host not found in upstream "app" in /etc/nginx/conf.d/default.conf:3Name in proxy_pass did not resolve at startup: default bridge, wrong name, backend stopped, or nginx on the hostSame 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 appVariable in proxy_pass but no resolver line; every request is a 502Add 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 existStart the backend; fix the name. Nginx keeps running and recovers by itself
[error] ... no live upstreams while connecting to upstreamWith resolve, the name has no address yet, so the group is emptyStart 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 startnginx -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.3Use the variable method, or the official image or nginx.org packages
[emerg] resolving names at run time requires upstream "backend" ... to be in shared memoryresolve without a zone lineAdd zone backend 64k; to the upstream
[emerg] no resolver defined to resolve names at run time in upstream "backend"resolve without a resolver directiveAdd 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 runVersion (19 November 2026)resolve in upstream?
Debian 13 package1.26.3 (lab)No: use the variable method
Ubuntu 26.04 LTS package1.28.3 (packages.ubuntu.com)Yes
Official image nginx:1.301.30.7 stable (lab)Yes, tested
nginx.org mainline1.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.

← All articles

Chat on Telegram