Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

nginx in a container returns 502 with 'connection refused' to another container

Errorconnect() failed (111: Connection refused) while connecting to upstream

Short answer

Inside a container, localhost is the container itself. If nginx proxies to localhost or to a host-published port, it knocks on its own door. Put both containers on one user-defined network, point proxy_pass at the other container's name and its internal port, and make the app listen on all interfaces.

  • Applies to Docker Engine 28, Docker Compose 2, nginx 1.28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Test the upstream from inside the nginx container, the same place nginx runs. The result shows whether the name resolves and the port answers.

    docker exec -it NGINX_CONTAINER sh -c 'getent hosts app; wget -qO- http://app:3000 | head -n 5'
  2. 2Match what you see, then jump to its fix

    1. 1The nginx log shows connection refused to 127.0.0.1 or [::1], and the config says proxy_pass http://localhost:PORTproxy_pass points at localhostFix
    2. 2getent hosts app prints nothing, or the name does not resolveThe two containers are not on the same user-defined networkFix
    3. 3The app is mapped like 8080:3000 and proxy_pass says app:8080proxy_pass uses the published host port instead of the container portFix
    4. 4The name resolves, but the connection is still refused; the app's start line says it listens on 127.0.0.1The app only listens on its own 127.0.0.1Fix

What does the error look like?

  • connect() failed (111: Connection refused) while connecting to upstream
  • 502 Bad Gateway

Cause 1 of 4

proxy_pass points at localhost

1Check

Each container has its own loopback interface, so localhost inside the nginx container is nginx's own container, where nothing listens on that port.

docker exec NGINX_CONTAINER grep -rn proxy_pass /etc/nginx/

2Fix

Use the other container's service or container name instead of localhost.

location / {
    proxy_pass http://app:3000;
}

3Verify

Test the config, reload nginx, and request the site.

docker exec NGINX_CONTAINER nginx -t
docker exec NGINX_CONTAINER nginx -s reload
curl -I http://localhost

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 4

The two containers are not on the same user-defined network

1Check

Names resolve only on user-defined networks. On the default bridge, containers reach each other by IP address and not by name. Compare the networks of both containers.

docker inspect -f '{{json .NetworkSettings.Networks}}' NGINX_CONTAINER
docker inspect -f '{{json .NetworkSettings.Networks}}' APP_CONTAINER

2Fix

Create a network and connect both containers to it. In Compose, services in one file share a project network by default.

docker network create web
docker network connect web NGINX_CONTAINER
docker network connect web APP_CONTAINER

3Verify

The name now resolves from inside the nginx container.

docker exec NGINX_CONTAINER getent hosts app

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 4

proxy_pass uses the published host port instead of the container port

1Check

A published port is the door from outside the host. Containers on the same network reach the container's own port. Read the mapping.

docker port APP_CONTAINER

2Fix

Proxy to the port the app listens on inside its container, here 3000, not the left-hand number of the mapping.

location / {
    proxy_pass http://app:3000;
}

3Verify

Repeat the first-step test from the nginx container.

docker exec NGINX_CONTAINER wget -qO- http://app:3000 | head -n 5

Confirmed by docs.docker.com

Did this fix it?

Cause 4 of 4

The app only listens on its own 127.0.0.1

1Check

A server bound to 127.0.0.1 inside its container accepts only that container's own connections, because the loopback is per container.

docker exec APP_CONTAINER cat /proc/net/tcp | head -n 5

2Fix

Bind the app to 0.0.0.0 (all interfaces) in its own settings or start command.

// Node.js example
app.listen(3000, '0.0.0.0');

3Verify

Restart the app container and repeat the first-step test.

docker restart APP_CONTAINER

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Use service names in Compose files and never localhost between containers.
  • Do not publish a port you only need between containers.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.