502 Bad Gateway

A 502 Bad Gateway is the HTTP status code returned when a server acting as a gateway or proxy received an invalid response from the upstream server it contacted. The proxy itself is working: it accepted your request and tried to pass it on. The failure is on the other side — the process, container, or host behind the proxy either did not answer correctly or did not answer at all. The visitor sees the 502 while the proxy logs the detail of what the upstream did wrong.

What it means

In a typical modern stack a reverse proxy such as Nginx, HAProxy, or a cloud load balancer sits in front of the application. The proxy is the “gateway”; the application, reached over a socket, a private port, or another host, is the “upstream”. When the proxy forwards a request and gets back a reply it cannot parse, or no reply at all, it reports a 502 to the client. The proxy's own health is not in question — it is telling you the upstream broke the conversation.

This makes 502 different from its neighbours. A 500 is the application saying it failed; a 504 is the upstream failing to answer within the time allowed; a 502 is the upstream answering badly or not being reachable by the proxy at all. When the upstream process is simply not running, the proxy cannot connect and usually returns 502 immediately. When the upstream answers but the reply is malformed — a truncated header, an unexpected reset — the proxy also returns 502. So the code points squarely at the link between proxy and application.

Because the proxy is healthy, the useful evidence lives in two places: the proxy's error log, which names the upstream and the reason, and the upstream's own log, which shows whether it crashed, restarted, or was overwhelmed.

Common causes

• The upstream application or container is stopped, crashed, or still starting up, so the proxy finds nothing to talk to.
• The proxy is configured to reach the upstream at the wrong address, port, or socket path after a change or migration.
• The upstream is overloaded and its worker pool is exhausted, so connections are reset or replies are cut short.
• A deploy, restart, or crash loop briefly takes the upstream offline while traffic keeps arriving.
• A proxy timeout is set too tightly, so a slow but valid upstream reply is discarded and reported as a bad gateway.

How to fix it

1. Read the proxy log entry. It names the upstream and the exact failure, which immediately narrows the cause.

   tail -n 50 /var/log/nginx/error.log
   journalctl -u nginx --since "10 min ago"

2. Confirm the upstream is running and listening. If the process is down, start it and watch whether it stays up.

   systemctl status myapp
   ss -lntp | grep 3000

3. Check that the proxy points at the right target. A wrong port or a stale Unix socket path after a redeploy is a classic cause. Verify the upstream block and reload.

   nginx -t
   systemctl reload nginx

4. Look at load and worker counts. If the upstream is saturating its worker pool, raise the pool or add instances so connections are not reset under pressure.
5. Revisit timeouts. A brief 502 during a slow response often means the proxy gave up too early; increase the relevant timeout only after confirming the upstream is genuinely completing the work.

How to prevent it

Health checks are the first defence. Have the proxy or load balancer poll a real endpoint that exercises the upstream, and remove instances that fail, so traffic never lands on a process that is down. Run enough application instances that one restart, deploy, or crash does not empty the pool, and use rolling deploys so new versions come up before old ones go away.

Keep a small amount of connection keep-alive between proxy and upstream to avoid a storm of reconnects, and make sure graceful shutdown lets in-flight requests finish before a process exits. Finally, monitor the upstream restart count and error rate: a rising number of restarts is the earliest warning that a 502 is coming. Watching those two signals is usually enough to catch the problem before visitors ever see the error.