Error guide

502 Bad Gateway

A proxy asked your application for a response and got something it could not use — or nothing at all.

A 502 Bad Gateway is generated by a proxy — nginx, a load balancer, a CDN — that forwarded your request to an upstream and received either nothing, or something that was not a valid HTTP response. The proxy is working correctly; it is reporting that the thing behind it is not.

That immediately narrows the search. Whatever failed, it failed on the far side of the proxy, and your application either was not running, was not reachable at the address the proxy uses, crashed mid-response, or answered with something malformed.

The most common single cause is an application process that died or is restarting. During a deploy this produces a brief burst of 502s that ends by itself, which is normal and is exactly why deploys should be watched rather than assumed. A 502 that does not clear on its own means the upstream did not come back.

Common causes

  • The application process crashed, was killed by the out-of-memory killer, or is mid-restart.
  • The proxy is configured with the wrong upstream address or port.
  • The application is listening only on localhost while the proxy connects over the network — or the reverse.
  • A container or pod failing its health checks and being taken out of rotation with nothing left to serve.
  • The upstream closing the connection before finishing the response.
  • A response header the proxy rejects — commonly an oversized header from an accumulated session cookie.

How to diagnose it

  1. Check whether the application process is running and listening, on the exact address and port the proxy is configured with.
  2. Read the proxy's error log, which usually names the failure precisely: connection refused, reset by peer, upstream prematurely closed.
  3. Request the upstream directly, bypassing the proxy, to establish whether it is answering at all.
  4. Check for out-of-memory kills and recent restarts in the host or container logs.
  5. If it started during a deploy and cleared, it was probably the restart window; if it did not clear, the new version is failing to start.

Whose fault is it? The server's side

Entirely server-side. The proxy is reporting honestly, and the failure is in the application or in the configuration linking the two.

What monitoring sees

A 502 fails an Uptimely check and the code is recorded, which is useful precisely because it distinguishes an upstream failure from the application returning its own 500. Deploy-window 502s are the standard case for muting a monitor for a fixed period: the mute stops incidents being declared while checks, status and uptime history continue truthfully.

Related error guides

Terms used on this page

Questions

What is the difference between 502 and 504?

A 502 means the upstream gave the proxy an unusable answer or none at all — usually because it is down. A 504 means the upstream was reachable and simply did not answer in time. Down versus slow.

Why do I get 502s during every deploy?

Because the old process stops before the new one is ready to serve. Rolling restarts, connection draining and a readiness check that the proxy respects remove the gap; muting the monitor for the window stops it paging while it exists.

One of the Uptimely HTTP and network error guides, written for the person who operates the server rather than the one refreshing the page. Something here read wrong to you? Email support@getuptimely.com.