HTTP 502 Bad Gateway: what it means and how to fix it
A 502 is your proxy telling you it couldn't get a valid response from your application. The fix is almost always one hop behind the proxy.
What an HTTP 502 actually means
HTTP 502 Bad Gateway means a server acting as a gateway or proxy — nginx, HAProxy, a cloud load balancer, or a CDN — received an invalid response (or no usable response at all) from the upstream server it forwarded the request to. The 502 page you see is generated by the intermediary, not by your application: the proxy tried to talk to the app and the conversation failed.
"Invalid response" covers several distinct failures: the connection was refused because nothing was listening, the upstream closed the connection before sending a complete response, the response was malformed, or the upstream process crashed mid-request. Each leaves a different fingerprint in the proxy's error log, which is why that log is the single most useful artifact when debugging a 502.
Common root causes of a 502
The upstream application crashed or isn't running
The app process died — an OOM kill, an unhandled crash, a failed restart after deploy — so the proxy has nothing to talk to. nginx logs this as "connect() failed (111: Connection refused) while connecting to upstream".
Connection refused between proxy and app
The app is running but not listening where the proxy expects: it bound to 127.0.0.1 while the proxy connects over the network, a firewall blocks the port, or the app is still starting and hasn't opened its socket yet. The proxy's connect attempt is rejected outright.
Upstream timeout shorter than the request
The app worker hit its own timeout (e.g. gunicorn or PHP-FPM killing a slow worker) and closed the connection before responding, so the proxy sees "upstream prematurely closed connection" and returns 502. Slow database queries and long external calls are the usual triggers.
Wrong upstream port, socket, or address
The proxy config points at the wrong port, a Unix socket path that doesn't exist or has wrong permissions, or a stale DNS/container address after a redeploy. Everything is "up", yet every request 502s because the two sides never meet.
How to investigate and fix a 502
Work from the proxy backwards: confirm the scope, read the proxy's error log to classify the failure, then verify the upstream's health, configuration, and resources.
- 1
Confirm the scope from outside
Is it every request or one route? One region or all? Constant or intermittent? A total 502 means the upstream is dead or misaddressed; intermittent 502s point to crashes under load, worker timeouts, or one bad instance behind the balancer.
- 2
Read the proxy's error log
nginx's error.log (or your LB's logs) tells you which failure happened: "connection refused" means nothing listening, "upstream prematurely closed" means the app died or timed out mid-request, "no live upstreams" means all backends were marked down. This single line usually decides the rest of the investigation.
- 3
Check upstream process health
On the app host: is the process running (systemctl status, docker ps, kubectl get pods)? Is it listening on the expected port or socket (ss -lntp)? If it crashed, the app's own logs and exit code tell you why — OOM kills show up in dmesg and as exit code 137.
- 4
Check the application's logs around the failures
Look for crashes, worker-timeout kills, restart loops, or startup errors at the timestamps of the 502s. A worker timeout in the app log paired with "prematurely closed" in the proxy log means the real problem is a slow request, not the proxy.
- 5
Check resource exhaustion
Memory pressure that triggers OOM kills, exhausted worker pools, file-descriptor limits, and full disks all produce 502s that come and go with load. Host metrics at the failure timestamps confirm or rule this out quickly.
- 6
Correlate with deploys and config changes
502s that begin exactly at a deploy usually mean the new version fails to start, binds to a different port, or the proxy config changed. Rolling back is the fastest mitigation while you diagnose the new version offline.
How to prevent 502 errors
- Use health checks on the proxy/load balancer so traffic only routes to upstreams that are actually accepting connections.
- Deploy with zero-downtime strategies (rolling or blue-green) so the old version keeps serving until the new one is listening.
- Align the timeout chain: app worker timeout, proxy read timeout, and load balancer timeout should be deliberate, not accidental.
- Monitor upstream memory and worker saturation so OOM kills and pool exhaustion are visible before they turn into 502s.
- Run external uptime checks on your public endpoints — a 502 is exactly the class of failure your application's own error tracking cannot see.
How AllStak helps with 502 errors
A 502 is generated in front of your application, so in-app error tracking alone won't catch it. AllStak's uptime monitoring probes your endpoints from outside and alerts the moment they start returning 502s — with response codes and timing — so you know about the outage before your users do.
From there, infrastructure monitoring shows whether the upstream host ran out of memory or the process died, and centralized logs put the proxy's "connection refused" line next to your app's crash log on one timeline. That correlation — outside check, host metrics, proxy log, app log — is what turns a vague 502 into a specific dead process.
HTTP 502 — frequently asked questions
What is the difference between a 502 and a 504?
Both come from a proxy, but they describe different upstream failures. A 502 means the proxy got an invalid or broken response — connection refused, connection closed early, malformed reply. A 504 means the upstream simply never answered within the proxy's timeout. 502 = bad answer; 504 = no answer in time.
What is the difference between a 502 and a 500?
A 500 is produced by your application itself after an internal failure — the app responded, with an error. A 502 is produced by the proxy because the app failed to respond validly at all. If you see a 500, look at app code; if you see a 502, look at app availability and proxy-to-app connectivity.
Can a CDN cause a 502?
Yes. A CDN is itself a proxy, so it returns 502 when it gets an invalid response from your origin — but it can also surface its own origin-connection problems (TLS handshake failures, origin firewall blocking the CDN's IPs). Check whether the 502 page is branded by the CDN or by your own proxy to see which hop failed.
Why do I get intermittent 502s only under load?
Under load, workers saturate, slow requests hit worker timeouts, memory pressure triggers OOM kills, and connection queues overflow — each produces occasional broken upstream responses. Check worker counts, memory at peak, and the proxy error log timestamps against your traffic curve.
Explore more
By framework
Compare
Catch the next 502 before your users do
AllStak's uptime checks watch your endpoints from outside while infrastructure monitoring and logs explain what happened behind the proxy — in one platform.