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.