Guides

502 Bad Gateway — what it means and how to fix it: 3 causes

Illustration: a courier standing at a closed door, parcel still in hand

You deploy your app, open the site — "502 Bad Gateway". The app logs are empty. Which, by the way, is the main clue.

Because 502 isn't served by your code. It's served by the proxy sitting in front of it — nginx, Caddy, your host's load balancer, Cloudflare. It dutifully knocked on your app's door and got no valid HTTP answer back.

That's why empty logs aren't "weird", they're expected: the request never reached your code.

Symptom: why this definitely isn't a bug in your code

There's a subtlety here that eliminates half the hypotheses immediately. MDN puts it like this: if the origin server sends the gateway a valid HTTP error response, the gateway should pass it on to the client instead of a 502.

In plain terms: if your code had crashed on an unhandled exception, you'd be looking at a 500 error, not a 502.

A 502 means something else — the app didn't answer by HTTP rules at all. It isn't running, it's listening somewhere else, or it dropped the connection mid-answer.

Once more, to remember it: 500 — "my code crashed". 502 — "nothing reached the code". The general logic of codes is in HTTP status codes.

Cause 1. The app isn't running, or it crashed

The most common one, especially right after a deploy. The process never came up — and the proxy doesn't know that, so it keeps knocking into the void.

How to check. Look at the process logs, not the web server's:

systemctl status myapp        # or: docker ps -a
journalctl -u myapp -n 50     # or: docker logs myapp --tail 50
pm2 logs myapp --lines 50

Don't read the last line — find the spot where the process died at startup. The usual suspects: a missing environment variable, a syntax error in fresh code, a busy port.

In the nginx log it looks like this:

connect() failed (111: Connection refused) while connecting to upstream

Connection refused is an unambiguous verdict: nobody is listening at that address.

How to fix. Bring the process up and make sure it doesn't die two seconds later (docker ps -a will show a Restarting status). If it died on env vars or the build, see why your deploy fails.

Cause 2. It's listening on the wrong address or port

The process is alive, and you still get Connection refused. A classic, with two traps.

Trap one: the port. The proxy forwards to 3000 while the app came up on 8080 — because it fell back to a default and PORT wasn't in the environment. Check both places, not one.

ss -tlnp | grep 3000     # who is actually listening on that port
curl -i localhost:3000   # does it answer, bypassing the proxy

If curl on the server answers but the domain returns 502, the problem is definitely in the proxy config. If curl doesn't answer either, it's in the app.

Trap two, sneakier: the address. The app listens on 127.0.0.1 instead of 0.0.0.0. On your machine you'd never notice — everything is in one place. But inside Docker, 127.0.0.1 means "this container only", and a proxy from outside will never get through.

app.listen(process.env.PORT || 3000, '0.0.0.0');

The tell for this exact cause: inside the container curl localhost:3000 works, from outside it doesn't. While you're there, check the port is actually published (-p 3000:3000) — and that nothing else grabbed it, as happens.

Cause 3. The process dies during the response

Rarer, but the longest to track down: the 502 hits some requests, not all — the heavy ones. One page opens, another doesn't.

The mechanics: the app started answering and died halfway. The proxy got a broken stream instead of a response — which is literally the definition of 502. Why:

  • The OOM killer got it. The container has 512 MB, and the request loads a big file or query result into memory. docker inspect will show OOMKilled: true; dmesg will have an Out of memory line.
  • A worker was recycled on timeout. gunicorn, puma and unicorn each have their own request-duration limit and kill the worker at it.
  • Database connections leaked. The pool is exhausted, new requests fail.

How to check. Open the logs on both sides and line them up by timestamp: at the moment of the 502 the app log will show either a cut-off mid-sentence or a worker restart.

If it's just slow, that's probably a 504

A separate fork people confuse with 502. When the app is alive but answers too slowly, the proxy doesn't wait forever. In nginx both key timeouts default to 60 seconds:

proxy_connect_timeout 60s;
proxy_read_timeout 60s;

Silence for longer than a minute and the client gets a 504 Gateway Timeout: "there was no answer at all". The distinction is exactly MDN's: 502 — something invalid arrived; 504 — nothing arrived.

So the first thing to establish is which code you're actually seeing. If it's 504, the fix is different — either speed the handler up, or move the long work to a background job and answer immediately.

If you're on Cloudflare, the code tells you more

A useful thing few people use. Behind Cloudflare you'll often see one of its own codes instead of 502, and each points at a specific place:

  • 521 Web Server Is Down — the origin refused the connection. Almost always cause 1 or 2 from this article.
  • 522 Connection Timed Out — the connection never got established. Usually a firewall blocking Cloudflare's IPs.
  • 523 Origin Is Unreachable — it can't find your server. Check DNS and the origin address.
  • 524 A Timeout Occurred — the connection is there, the answer isn't. This is "their 504" — it's about handler speed.
  • 520 — the origin returned something Cloudflare couldn't parse.

So the code has already narrowed the search for you. Read it before you dive into config files.

How is 502 different from 500?

By where it broke. 500 — the request reached your app and the code crashed there: look for a stack trace in the logs. 502 — the request never reached the app, or the response was cut off: check whether it's alive and listening on the right address.

Why does everything work locally?

Because locally there's usually no proxy — the browser talks straight to the app. All three causes disappear at once: the address matches, there's one port, memory isn't capped. To reproduce a 502 on your machine you'd have to recreate the setup — a memory-limited container with nginx in front.

Debugging is a skill built out of forks exactly like this: where did it break. In KODiQ we walk through them in plain language, step by step, on real errors.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →