nginx in a container returns 502 with 'connection refused' to another container
connect() failed (111: Connection refused) while connecting to upstreamShort 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.
Fix it fast
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'2Match what you see, then jump to its fix
- 1
The 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
getent hosts app prints nothing, or the name does not resolveThe two containers are not on the same user-defined networkFix - 3
The app is mapped like 8080:3000 and proxy_pass says app:8080proxy_pass uses the published host port instead of the container portFix - 4
The 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
- 1
What does the error look like?
connect() failed (111: Connection refused) while connecting to upstream502 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://localhostConfirmed by docs.docker.com
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_CONTAINER2Fix
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_CONTAINER3Verify
The name now resolves from inside the nginx container.
docker exec NGINX_CONTAINER getent hosts appConfirmed by docs.docker.com
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_CONTAINER2Fix
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 5Confirmed by docs.docker.com
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 52Fix
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_CONTAINERConfirmed by docs.docker.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
Related fixes
Servers
Reaching a service on the host's localhost from inside a Docker container
getaddrinfo ENOTFOUND host.docker.internal
Inside a container, localhost is the container itself, not your machine.
5 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
Docker php image has no php.ini and my edits do not stay
A setting changed in php.ini inside the container is gone after the container is recreated
The official php image ships php.ini-development and php.ini-production but no active php.ini.
2 causes, each with a fixServers
The MinIO Console will not work behind an nginx proxy: no login, 403 on the WebSocket, or repeated disconnects
The Console UI shows repeated disconnects
Behind a proxy the MinIO Console needs three things.
4 causes, each with a fixServers
nginx returns 403 and logs directory index is forbidden
directory index of "/usr/share/nginx/html/" is forbidden
nginx got a request for a folder, found none of the index files it was told to look for, and listing the folder is off by default.
3 causes, each with a fixServers
The nginx container serves the default page or 404 because /usr/share/nginx/html has no app files
requests for your pages return 404 Not Found
The official nginx image serves whatever sits in /usr/share/nginx/html.
3 causes, each with a fix