HTTP 502 Bad Gateway
What a 502 Bad Gateway response means, why it happens, and the fastest ways to fix it.
A proxy or load balancer got an invalid (or no) response from the upstream server behind it. The proxy is fine; the thing behind it is not.
- Upstream app crashed or is restarting (deploys!).
- Upstream timeout shorter than the app's response time.
- Wrong upstream port/socket in nginx config.
- Container not listening yet when the LB health check passes.
- Check whether the upstream process is running and listening on the expected port.
- Look at proxy error logs (nginx: connect() failed / upstream prematurely closed).
- Add health checks and graceful-shutdown draining around deploys.
Notes
HTTP status codes are defined in RFC 9110 (which replaced RFC 7231). The first digit is the class: 1xx informational, 2xx success, 3xx redirection, 4xx client error, 5xx server error.
Same class: 500 · 501 · 503 · 504 · 505 · 507
All codes: HTTP status code reference
Frequently asked questions
What does HTTP 502 mean?
HTTP 502 Bad Gateway: A proxy or load balancer got an invalid (or no) response from the upstream server behind it. The proxy is fine; the thing behind it is not.
How do I fix a 502 error?
Check whether the upstream process is running and listening on the expected port. Look at proxy error logs (nginx: connect() failed / upstream prematurely closed). Add health checks and graceful-shutdown draining around deploys.
Is a 502 my fault or the server's?
502 is a server error — something on the server side (or between the proxy and the app) failed.