You refresh your site and there it is: 502 Bad Gateway. No friendly explanation, no hint — just a blunt grey error. The good news is that 502 is actually one of the more informative errors, once you understand who's talking to whom. Let's decode it.
What a 502 actually means
Most modern sites don't serve traffic directly from the application. There's something in front — a reverse proxy, load balancer or CDN (Nginx, a cloud load balancer, Cloudflare). The request flow looks like this:
Browser ──► Proxy / load balancer ──► Your app (upstream)
A 502 Bad Gateway means: the proxy reached your app, but got back something it couldn't use — an empty response, a crash, garbage, or nothing at all. In plain terms:
502 = "the thing behind me is broken." The proxy is fine and doing its job; it's reporting that your upstream application failed to give a valid answer.
That's why a 502 is a useful clue: it points you straight past the proxy, at your app.
The usual causes
| Cause | What happened |
|---|---|
| App crashed | The application process died and isn't responding at all |
| App not listening | It's not running on the port/socket the proxy expects |
| Deploy in progress | The old process stopped before the new one was ready |
| Out of memory / resources | The app was killed mid-request |
| Upstream timeout | The app took too long (though this often shows as 504) |
| Bad proxy config | The proxy is pointing at the wrong upstream address |
The most common by far: the application crashed or restarted and the proxy has nothing healthy to talk to.
How to fix it
Work from the app outward:
- Check if your app is actually running. Is the process up? Listening on the expected port? This catches most 502s immediately.
- Read the application logs. A 502 from the proxy usually has a matching crash or error in your app's logs — that's your real root cause.
- Restart the app (if it crashed) to restore service, then investigate why it crashed so it doesn't recur.
- Check resources. Out-of-memory kills are a classic silent cause — check memory and CPU.
- Verify the proxy config. If the app is healthy but you still get 502s, the proxy may be pointing at the wrong place.
- Look at recent deploys. A 502 right after a release usually means the deploy left no healthy process to serve traffic.
502 vs 503 vs 504 — don't mix them up
These three 5xx codes look similar but tell different stories:
| Code | Meaning | Mental shortcut |
|---|---|---|
| 502 Bad Gateway | Upstream gave an invalid/no response | The app is dead |
| 503 Service Unavailable | Server is up but can't serve now | Overloaded or in maintenance |
| 504 Gateway Timeout | Upstream took too long to respond | The app is slow |
If you remember one thing: 502 = dead upstream, 504 = slow upstream, 503 = deliberately unavailable.
How to prevent it
502s are usually a symptom of an app that fell over — so prevention is about resilience and early warning:
- Health checks + graceful deploys. Don't route traffic to a new version until it's actually ready, and don't kill the old one too early. (Staged rollouts make this safe.)
- Auto-restart on crash. A supervisor that restarts a dead process turns a long outage into a blip.
- Right-size resources. Avoid the out-of-memory kills that cause sudden 502s.
- Monitor for them. The faster you know 502s are happening, the faster you fix them — ideally before customers notice.
The bottom line
| In one line | |
|---|---|
| What | The proxy couldn't get a valid response from your app. |
| Where to look | Your app, not the proxy — check it's running and read its logs. |
| 502 vs 504 | Dead upstream vs slow upstream. |
| Prevent | Health checks, graceful deploys, auto-restart, monitoring. |
A 502 isn't a mystery — it's your proxy pointing at your app and saying "this isn't answering." Follow the finger, check your app, and you'll usually find the cause in minutes.
More error codes in HTTP status codes explained, and set up alerts on 5xx spikes with the web monitoring guide.