Debugging 502 Bad Gateway Errors

What Does 502 Mean?

A 502 Bad Gateway error means a server acting as a gateway or proxy received an invalid response from an upstream server. The problem is NOT with the client — it's between your proxy (Nginx, Cloudflare, etc.) and your application server.

Common Causes

1. Application Server Is Down

The most common cause. Your app server (Gunicorn, uWSGI, Node.js) has crashed or isn't running.

# Check if your app process is running
sudo systemctl status gunicorn
sudo systemctl status your-app

2. Socket/Port Mismatch

Nginx is trying to connect to a socket or port that the app isn't listening on.

# Check Nginx upstream config
grep proxy_pass /etc/nginx/sites-enabled/your-site
# Verify the app is listening
ss -tlnp | grep :8000

3. Timeout on Large Requests

The upstream server is taking too long to respond.

# Increase Nginx proxy timeouts
proxy_read_timeout 300;
proxy_connect_timeout 300;

4. Memory Exhaustion (OOM)

The application was killed by the OS due to out-of-memory.

# Check for OOM kills
dmesg | grep -i 'out of memory'
journalctl -k | grep -i oom

Quick Fix Checklist

Is the app process running?
Is it listening on the correct port/socket?
Check app logs for errors
Check for OOM kills
Restart the app and verify