502Bad Gateway
A proxy passed your request on and got back something that was not a valid response.
How you get a 502
The app process has crashed. The proxy forwards the request and the connection is refused at once. With nothing valid to pass back, the proxy writes the 502 itself.
Who sends itProxy · CDN
- Browser
- CDN
- Proxy
- App
- DB
Typically the reverse proxy, load balancer or CDN in front of the app. The app itself almost never sends a 502, unless it is acting as a gateway to another service.
In short
What a 502 Bad Gateway means
A 502 Bad Gateway is written by a middle box, not by your application. A reverse proxy, load balancer or CDN accepted the request, forwarded it to the server behind it, and got back something it could not use: a refused connection, a connection that closed halfway through, or bytes that are not valid HTTP. The proxy cannot invent the real answer, so it sends its own error page with status 502. Two things set it apart from its neighbours. It is fast, because the failure is immediate and nobody waits for a timer. And the application usually has no record of the request, because it was down, restarting or crashed before it could log anything. Start in the proxy's error log, which names the upstream it tried and what went wrong.
Common causes of a 502
1The app process is down or restarting (deploy, crash, out-of-memory kill).
How to check: Look in the proxy's error log for a refused connection to the upstream.
connect() failed (111: Connection refused) while connecting to upstream2The app crashed or was killed partway through the response.
How to check: The proxy log shows the upstream closing early; the app log stops mid-request.
upstream prematurely closed connection while reading response header from upstream3The proxy points at the wrong host or port, or at an address that changed after a redeploy.
How to check: From the proxy machine, call the upstream address directly.
curl -sv http://<upstream-host>:<port>/health4The app closes idle keep-alive connections sooner than the load balancer does, so a reused connection is already dead.
How to check: Sporadic 502s that fail instantly. On an AWS ALB the access log shows no target time.
target_processing_time = -15The app's response headers are larger than the proxy's buffer (huge cookies or tokens).
How to check: nginx names this one directly in its error log.
upstream sent too big header while reading response header from upstream
Retry or not?
Safe to retry with backoff · Idempotent requests
Headers that matter
- Server / Via
- Tells you which hop wrote the error page (nginx, cloudflare, awselb). That is the box whose logs to read first.
- cf-ray / x-amzn-trace-id
- The edge's request ID. Use it to find the matching line in the CDN or load balancer logs.
- Retry-After
- Rarely present on a 502. If a proxy does send it, honour it.
In the real world
RFC vs real deployments
RFC 9110 defines 502 as an invalid response from the server behind a gateway. Real proxies stretch that to cover no response at all: nginx sends 502 when the connection is refused or reset, and also when every server in an upstream group is marked down. Not every product agrees. Envoy reports a refused upstream connection as 503, so the same failure can show up under either code depending on what sits in front of your app.
Seen in a real outage
5xx errors that arrive in waves, clear, and come back usually mean the process that should answer keeps dying and restarting. That is the shape of Cloudflare's November 2025 outage, where proxies crashed on a bad file that alternated with a good one.
Your turn
Which code is it?
Right after a deploy, some requests fail for about 20 seconds. Each failure returns in a few milliseconds with an nginx error page, and the nginx log says “Connection refused”. Which code did users get?
Often confused with
502 questions
- Who sends a 502 Bad Gateway?
- Typically a reverse proxy, load balancer or CDN, not the application. It sends 502 when the server behind it refuses the connection, drops it, or returns something that is not valid HTTP.
- What is the difference between 502 and 504?
- Both come from a proxy. With 502 the proxy got a broken answer straight away. With 504 it got no answer before its timeout ran out. A 502 fails fast; a 504 takes exactly as long as the proxy's timeout.
- How do I fix a 502 on nginx?
- Read the nginx error log first: it names the upstream and the reason. Then check that the app process is running, that it listens on the address nginx is configured with, and that it is not being killed for using too much memory.
Sources: RFC 9110: 502 Bad Gateway (section 15.6.3) ↗ · nginx: ngx_http_proxy_module ↗ · AWS: Troubleshoot your Application Load Balancer ↗ · Report a problem
Diagrams are our own simulations. All wording is original and paraphrases the linked sources.
Practise this in the DNS / HTTP track
Two-minute animated lessons, then boss fights from real outages. Free, no account needed.