UUID Studio

502 Bad Gateway

A server acting as a gateway received an invalid response from an upstream server.

What 502 means

502 comes from something in front of your application - a load balancer, reverse proxy, CDN or API gateway - and it means the upstream gave an answer the proxy could not use. Often that means no answer at all: the connection was refused, or reset, or closed before a complete response arrived.

The distinction from 504 is worth holding onto. A 504 means the upstream was too slow; a 502 means it responded, but unusably, or died mid-response. In practice a 502 usually means the application process is not running, not listening where the proxy expects, or crashed while handling the request.

The most common operational cause is a deployment: the old process has stopped and the new one is not yet accepting connections, so every request in that window gets a 502. Graceful shutdown and readiness probes exist to close that gap.

Because the error is generated by the proxy, your application logs may show nothing at all - which is itself diagnostic. If the proxy reports 502 and the application has no record of the request, the request never arrived.

Common causes of a 502

  • The upstream application process is not running or has crashed.
  • The application is listening on a different port or interface than the proxy expects.
  • A deployment window where the old process stopped before the new one was ready.
  • The upstream closed the connection mid-response - often an out-of-memory kill.
  • A response with malformed headers that the proxy refused to forward.
  • A response exceeding the proxy's buffer limits.
  • TLS negotiation failure between proxy and upstream, including an expired internal certificate.

How to fix a 502

  • Check whether the application process is running and listening where the proxy expects.
  • Compare proxy logs against application logs - if the app has no record, the request never arrived.
  • Add readiness probes and graceful shutdown so deployments do not drop connections.
  • Look for OOM kills in the system log around the failure.
  • Check internal certificate expiry if proxy-to-upstream traffic is TLS.

Should a client retry?

Frequently transient - especially during a deploy - so retry with backoff. If it persists, the upstream is down and retrying will not help.

FAQ

What is the difference between 502 and 504?
504 means the upstream did not respond in time. 502 means it responded with something the proxy could not use, or closed the connection - most often because the process is not running or crashed mid-request.
Why do I get 502s during every deployment?
Because the old process stops accepting connections before the new one is ready. Use readiness probes so traffic only arrives once the new process can serve it, and graceful shutdown so in-flight requests finish.
My application logs show nothing for a 502 - why?
Because the proxy generated the error. If the application has no record of the request, it never reached it - look at whether the process was running and listening on the expected address.

Often confused with