502 Bad Gateway
A proxy or load balancer forwarded your request upstream and got garbage or nothing back: connection refused, connection reset, or an unparseable response. The proxy is fine; the thing behind it is not. First question: is the application process actually running?
What usually causes it
- Application crashed or is restarting (deploy in progress)
- Proxy pointed at the wrong port/socket
- Upstream closing connections mid-response (OOM kills are a classic)
- TLS mismatch between proxy and upstream
How to debug and fix it
- Check process liveness first (systemctl status / container restarts / OOMKilled events) — most 502s are 'the app is down'.
- Curl the upstream directly, bypassing the proxy, to isolate which side fails.
- During deploys, 502 blips mean traffic shifted before the new instance was ready — wire up health-check-gated rollouts.
- Check proxy error logs (nginx: connect() failed / upstream prematurely closed) — they name the exact failure.
Easily confused with
Debugging an API? Build and inspect requests, check response headers, or read the full status-code debugging guide.