Skip to content
Fix These Errors
HTTP 502 Bad Gateway — What It Means & How to Debug

HTTP 502 Bad Gateway — What It Means & How to Debug

DodaTech Updated Jun 20, 2026 4 min read

HTTP 502 Bad Gateway is an HTTP response status code that indicates a server acting as a gateway or proxy received an invalid response from an upstream server it accessed while fulfilling the request. The 502 is one of the most common reverse-proxy errors, appearing when Nginx, a CDN, or an API gateway cannot get a valid response from the backend application server.

What It Means

Defined in RFC 7231 Section 6.6.3, the 502 status code signals a breakdown in server-to-server communication. The gateway or proxy successfully established a TCP connection to the upstream server and sent the request, but the response it received was malformed, incomplete, or otherwise invalid. The proxy cannot forward a response it cannot parse.

When It’s Sent

  • Upstream server crash — The application server (e.g., uWSGI, Gunicorn, Puma) crashed or was killed after the proxy forwarded the request.
  • Upstream returns garbled data — The backend responds with non-HTTP content, binary garbage, or an unparseable response body.
  • SSL/TLS handshake failure — The proxy cannot establish a secure connection to the upstream.
  • Upstream protocol mismatch — The proxy speaks HTTP/1.1 but the upstream speaks only HTTP/2, or vice versa.
  • Upstream timeout with partial response — The backend begins sending a response but the connection drops before the headers or body are complete.
  • CDN origin unreachable — A CDN edge node cannot fetch content from the origin server.

Real Example

The following curl command hits an endpoint configured with a broken upstream:

curl -v https://httpbin.org/status/502

Expected response:

< HTTP/1.1 502 BAD GATEWAY
< Date: Sat, 20 Jun 2026 12:00:00 GMT
< Content-Type: text/html; charset=utf-8
< Content-Length: 184
< Server: gunicorn/19.9.0
<
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>502 Bad Gateway</title>
<h1>Bad Gateway</h1>
<p>The server returned an invalid or incomplete response.</p>

A real-world Nginx 502 with a broken upstream might look like:

<html>
<head><title>502 Bad Gateway</title></head>
<body>
<center><h1>502 Bad Gateway</h1></center>
<hr><center>nginx/1.24.0</center>
</body>
</html>

How to Debug

Client-Side

  1. Retry after a short delay — A 502 is often transient (upstream restart, deployment). Retry with backoff.
  2. Check the proxy service status — If you are hitting a CDN (Cloudflare, Akamai) or API gateway, check that service’s status page for outages.
  3. Try direct access — If you know the upstream server’s address, bypass the proxy and see if the backend responds directly.
  4. Clear DNS cache — A stale DNS entry might point to a dead backend the proxy cannot reach.

Server-Side

  1. Check upstream health — Verify the application server is running: ps aux | grep gunicorn or check systemd status.
  2. Review upstream logs — The application server logs often have the real error. Look for crashes, timeouts, or out-of-memory events.
  3. Check proxy error logs — Nginx logs upstream prematurely closed connection or upstream sent no valid HTTP response. Apache logs (20014)Internal error in the error log.
  4. Inspect upstream port and socket — Make sure the proxy is pointing to the correct port or Unix socket. A common mistake is a misaligned port after a deploy.
  5. Verify upstream returns valid HTTP — Use curl directly against the upstream to confirm it returns proper HTTP with complete headers.
  6. Check for resource exhaustion — If the upstream runs out of file descriptors, memory, or worker threads, it may drop connections mid-response.

Common Causes Table

ScenarioLikely CauseHow to Fix
App server restarted during deployBrief window with no running workersUse zero-downtime deploys with rolling restarts
Nginx returns 502 after deployUpstream bind port changedUpdate proxy_pass to the correct port/socket
CDN returns 502 on origin pullOrigin server is down or overloadedScale origin; enable CDN origin shielding
SSL handshake failureUpstream certificate expired or self-signedRenew certificate; configure proxy to trust upstream CA
Upstream returns HTTP/0.9 responseBackend sends raw data without HTTP headersEnsure backend returns proper HTTP response

FAQ

Is 502 the same as 504?
No. A 502 means the proxy received an invalid or corrupt response from the upstream. A 504 means the proxy did not receive any response within the timeout period.
Why does my site show 502 after a deployment?
The application server is likely still restarting when the proxy forwards the first request. Use a health check endpoint and configure the proxy to only route traffic to healthy upstreams. Implement graceful startup delays.
Can a client fix a 502 error?
Sometimes. If the error is caused by a DNS issue, flushing DNS or switching networks may help. In most cases, however, a 502 requires server-side intervention to fix the upstream server.

Related Codes

HTTP 504 Gateway Timeout — The upstream server did not respond in time.

HTTP 503 Service Unavailable — The server is temporarily unable to handle the request.

HTTP 500 Internal Server Error — A generic server-side error.

HTTP 502 Bad Gateway — The gateway received an invalid upstream response.

Previous commit your changes or stash them before you can merge Next HTTP 503 Service Unavailable — What It Means & How to Debug

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Fix These Errors