502 Bad Gateway

Almost no website is a single machine any more. Between you and the code that builds a page there is usually a CDN, then a load balancer, then a reverse proxy, then the application itself. A 502 tells you that this chain broke at a specific link: One of the machines in the middle asked the machine behind it for a response, and what came back was not a valid HTTP response.

That is why 502 is such a useful error, despite being frustrating. It tells you the site exists, the DNS is correct, the network path is fine, and something is listening on the right port. The failure is one hop further in.

What produces one

• The application process is not running. It crashed, or was killed by the operating system for using too much memory, or was stopped during a deploy and has not come back. The proxy connects to the socket, finds nothing, and returns 502.
• The application crashed mid-response. It started answering and died partway through, leaving the proxy with a truncated response it cannot forward.
• It returned something that is not HTTP. Usually a startup error or a stack trace written to standard output where a response should have been.
• A deploy is in progress. Old processes have stopped and new ones have not finished starting. This window should be zero with a proper rolling deploy, but not every deploy is proper.
• The connection pool is exhausted. Every upstream worker is busy, the proxy cannot get a connection, and it gives up.
• The origin is unreachable from the CDN. A firewall rule, an origin IP change, or a certificate the CDN will not accept.

Why it usually clears quickly

Because the most common cause is a process that died, and process supervisors exist precisely to restart processes that die. Systemd, a container orchestrator, a platform supervisor - All of them notice a dead worker within seconds and start another.

So the typical 502 is measured in seconds to a couple of minutes. A 502 that persists for longer is a different and more interesting problem: It usually means the application is crashing on startup, in a loop, which means a deploy has shipped something broken. That needs a human and a rollback.

502 versus 504

These two are constantly confused and mean genuinely different things.

A 502 means the upstream answered wrongly or not at all - The connection failed, or the response was invalid. It is fast: The proxy knows immediately.

A 504 means the upstream did not answer in time. The connection succeeded, the request was accepted, and then nothing came back before the proxy's timeout expired. It is slow by definition - You usually wait thirty or sixty seconds before seeing it.

The diagnostic implication is different too. A 502 says the application is not there. A 504 says the application is there and stuck, which usually means a slow database query or a blocked external call.

When the 502 has branding on it

If the error page carries a company's logo, that company's edge network is reporting that it could not reach the origin. Cloudflare pages carry a ray ID and often a more specific number in the 520–527 range, which narrows the cause considerably - Each of those means something particular.

This is worth noticing because it tells you which company is having the problem. A Cloudflare-branded 502 usually means the customer's origin server is down, not that Cloudflare is. A plain 502 from the site's own infrastructure means the problem is entirely theirs.

What to do as a visitor

Reload once, wait thirty seconds, reload again. That covers the overwhelming majority of 502s, which are a worker that died and has already been replaced.

If it persists, check the site from another network to confirm it is not specific to your route, and then stop. There is nothing on your side involved in a 502 - Your request reached their infrastructure successfully, which is more than you can say for most errors.

If it is your site

Look at the application, not the proxy. The proxy is telling you the truth.

1. Is the process running? Check the supervisor. If it is restarting repeatedly, you have a crash loop and the application log has the reason.
2. Is it listening where the proxy expects? A port or socket path mismatch after a configuration change is a classic.
3. Memory. Check whether the kernel OOM killer has been terminating the process. This is the most commonly missed cause on small servers, and the application log shows nothing because the process was killed rather than crashing.
4. Upstream timeouts and buffer sizes. In nginx, an oversized response header can produce a 502 even when the application is perfectly healthy.
5. For a CDN 502: Confirm the origin is reachable from outside your own network, that its certificate is valid, and that the CDN's address ranges are not blocked by your firewall.