Nginx 502 Bad Gateway in Docker: Read the Log, Fix the Cause

• A few seconds of 502 on every deploy

  Recreating the container leaves a gap: the old one is gone and the new app is not listening yet, so nginx logs refused connections, then resets, then nothing. If the 502 lines stop by the time docker ps shows the new container healthy, that gap is the whole story. Closing it takes a second copy of the app to switch to, which is what blue-green deploys do.

• Still 502 after the app container came back

  With nginx in a container on the same network, nginx resolved the app's name when it loaded its config. A recreated container gets a new address, and nginx keeps sending to the old one: connect() failed with Connection refused or Host is unreachable. Run nginx -s reload in the nginx container so it looks the name up again, or use the upstream resolve parameter so it follows changes by itself.

• nginx will not start: host not found in upstream

  nginx resolves every name in proxy_pass when it loads its config and exits with [emerg] host not found in upstream if one does not resolve, so docker logs shows the line and the container stops. Check the name against the Compose service name, and check that nginx and the app share a network.

• upstream sent too big header, and raising one buffer fails

  A response whose headers outgrow proxy_buffer_size gets a 502 even though the app answered. In a test, raising proxy_buffer_size to 16k alone failed nginx -t with "proxy_busy_buffers_size" must be less than the size of all "proxy_buffers" minus one buffer. Adding proxy_buffers 8 16k passed and fixed the 502. Trimming oversized cookies or headers is the better fix.

1. 1

   Create a network and a tiny app that listens on the HOST and PORT you give it, port 3000 by default. /slow answers after 10 seconds. APP keeps the code for the steps that recreate it.

   docker network create demo502-net
   APP="require('http').createServer((req, res) => setTimeout(() => res.end('hello\n'), req.url === '/slow' ? 10000 : 0)).listen(process.env.PORT || 3000, process.env.HOST)"
   docker run -d --name demo502-app --network demo502-net -e HOST=0.0.0.0 node:22-alpine node -e "$APP"

   Copy
2. 2

   Write an nginx config that proxies to the app by name, with a 5-second read timeout so the 504 comes quickly, and start nginx on the same network. curl prints hello.

   printf 'server {\n  listen 80;\n  location / {\n    proxy_pass http://demo502-app:3000;\n    proxy_read_timeout 5s;\n  }\n}\n' > demo502.conf
   docker run -d --name demo502-nginx --network demo502-net -p 127.0.0.1:8090:80 \
     -v "$PWD/demo502.conf:/etc/nginx/conf.d/default.conf:ro" nginx:alpine
   curl http://127.0.0.1:8090

   Copy
3. 3

   Break it once: stop the app. After a pause of several seconds, curl gets nginx's own 502 page, and the log says connect() failed (113: Host is unreachable) while connecting to upstream. nginx still uses the address it looked up at start, and nothing answers there now.

   docker stop demo502-app
   curl -i http://127.0.0.1:8090
   docker logs demo502-nginx 2>&1 | grep '\[error\]' | tail -1

   Copy
4. 4

   Break it twice: run the app on port 3001 while nginx still proxies to 3000, and reload nginx so it looks the name up again. Now the log says connect() failed (111: Connection refused), and netstat inside the app shows 0.0.0.0:3001.

   docker rm -f demo502-app
   docker run -d --name demo502-app --network demo502-net -e HOST=0.0.0.0 -e PORT=3001 node:22-alpine node -e "$APP"
   docker exec demo502-nginx nginx -s reload
   curl -i http://127.0.0.1:8090
   docker logs demo502-nginx 2>&1 | grep '\[error\]' | tail -1
   docker exec demo502-app netstat -tln | grep 300

   Copy
5. 5

   Break it a third time: the right port, but the app listens only on the container's 127.0.0.1. The log shows the same refused connection, and netstat shows why: 127.0.0.1:3000 instead of 0.0.0.0:3000.

   docker rm -f demo502-app
   docker run -d --name demo502-app --network demo502-net -e HOST=127.0.0.1 node:22-alpine node -e "$APP"
   docker exec demo502-nginx nginx -s reload
   curl -i http://127.0.0.1:8090
   docker logs demo502-nginx 2>&1 | grep '\[error\]' | tail -1
   docker exec demo502-app netstat -tln | grep 300

   Copy
6. 6

   Fix it with HOST=0.0.0.0, and curl prints hello again. Then ask for /slow: after 5 seconds nginx gives up with 504 Gateway Time-out, logged as upstream timed out (110: Operation timed out) while reading response header from upstream.

   docker rm -f demo502-app
   docker run -d --name demo502-app --network demo502-net -e HOST=0.0.0.0 node:22-alpine node -e "$APP"
   docker exec demo502-nginx nginx -s reload
   curl http://127.0.0.1:8090
   curl -i http://127.0.0.1:8090/slow
   docker logs demo502-nginx 2>&1 | grep '\[error\]' | tail -1

   Copy
7. 7

   Clean up the containers, the network and the config file.

   docker rm -f demo502-nginx demo502-app
   docker network rm demo502-net
   rm demo502.conf

   Copy

From: 24. GitHub Actions Secrets Tutorial: Variables, Scopes and Forks · 22. Linux File Permissions Explained: ls -l, chmod, chown, umask

1. 1.Your browser shows 502 Bad Gateway with nginx at the bottom of the page. Which component failed?Show the answer

   Answer:Not nginx: it took the request and built that page. Its upstream, the app behind it, refused, reset or closed the connection, or sent something nginx could not use. The error-log line says which.

2. 2.What is the difference between while connecting to upstream and while reading response header from upstream?Show the answer

   Answer:The first means nginx never got a connection: nothing listening, a wrong port or a stale address. The second means it connected, but the start of the answer never came, came broken or came too late.

3. 3.A 502 page carries Cloudflare's branding. Where do you look first?Show the answer

   Answer:At your origin. Cloudflare's docs say a branded 502 or 504 came from the origin web server, so read nginx's error log. A blank, unbranded 502 is Cloudflare's own.

• how to set up an nginx reverse proxy for Docker behind Cloudflare
• nginx load balancer config in production: timeouts and health checks
• how to read Docker logs: tail, follow and Compose