502 Bad Gateway — What It Means and How to Fix It

What 502 means

Something in front of your application — nginx, a load balancer, a CDN — tried to reach your application and got either nothing or something it could not parse. The proxy is working correctly; it is reporting that whatever sits behind it is not.

Common causes

•The application process crashed or was never started.
•The application is listening on a different port or socket than the proxy expects.
•The application crashed mid-response, sending a truncated reply.
•An upstream deploy restarted workers without connection draining.
•The proxy pointing at a stale container or IP after a redeploy.
•Response headers exceeding the proxy's buffer size.

How to fix it

Check whether the application process is actually running before touching anything else — a 502 most often means it is not. If it is running, confirm the proxy's upstream address matches where the app is listening; a port or socket path mismatch after a config change produces this immediately and consistently. Intermittent 502s during deploys usually mean connections are not being drained before workers restart.

Catching 502 before your users report it

This is one of the most valuable codes to monitor for, because your server responds instantly and the site is completely unusable. Ping checks and TCP checks both pass. Only an HTTP check that inspects the status code catches it.

Monitor for 502 responses free

Often confused with

503 Service Unavailable 504 Gateway Timeout 500 Internal Server Error

← All HTTP status codes

502 Bad Gateway — questions

What causes a 502 Bad Gateway error?

Most commonly the application behind the proxy is not running or not reachable at the address the proxy expects. The proxy itself is healthy — that is why it is able to return an error page at all.

Is a 502 error my problem or the host's?

If you control the application behind the proxy, it is usually yours: the app crashed, or the proxy is pointed at the wrong place. If you are a visitor, there is nothing you can do beyond waiting.

Why do I get 502 errors only during deploys?

Workers are being restarted without draining in-flight connections. The proxy forwards a request to a worker that shuts down before replying. Graceful reload with overlapping workers fixes it.

502