502 Bad Gateway with Nginx: The Usual Causes

Nginx returns a 502 Bad Gateway and panic sets in. Don't — a 502 has a very specific meaning, and that narrows the hunt dramatically. It means Nginx is working fine but couldn't get a valid response from the app behind it. So the problem is almost always your app or the link to it, not Nginx itself.

Cause 1: Your app isn't running

The most common reason by far. Nginx forwarded the request and found nothing listening. Check that your app process is actually up:

ps aux | grep yourapp
ss -ltnp | grep :8000     # is anything listening on the app's port?

If your app isn't there, that's your 502. Start it (and find out why it stopped).

Cause 2: Wrong address or port in the config

Nginx forwards to an address you configured (a proxy_pass). If that host or port doesn't match where your app actually listens, every request 502s. Confirm the port in your Nginx config matches the app's real port.

Cause 3: The app crashed on this request

If the app is generally up but a specific request kills it or times out, you'll get intermittent 502s. The app's own logs are the place to look here, not Nginx.

Always read the Nginx error log

It usually names the exact problem — connection refused, timeout, and so on:

tail -f /var/log/nginx/error.log

"Connection refused" in that log almost always means the app isn't listening where Nginx expects. That single line solves most 502s.

The checklist

1. Is the app process running?
2. Is it listening on the port Nginx forwards to?
3. Does the proxy_pass address/port match reality?
4. What does /var/log/nginx/error.log say?

Work that list top to bottom and you'll resolve the overwhelming majority of 502s in minutes.

Frequently Asked Questions

What causes a 502 Bad Gateway in Nginx? Nginx is working — the app it proxies to (the "upstream") isn't reachable. Almost always the backend is not running, is listening on a different port than proxy_pass expects, or crashed while handling the request.

How do I fix an Nginx 502 Bad Gateway? Confirm the backend process is running and listening on the exact host/port in your proxy_pass, then check /var/log/nginx/error.log — it usually names the precise cause (connection refused, timeout, and so on).

Is a 502 error the client's fault or the server's? Server-side. Nginx itself is up and answering, but the upstream service behind it failed — so fixing it means looking at your app, not the browser.