502 Bad Gateway

What It Means

A 502 error occurs when a server acting as a gateway or proxy (like Nginx, a CDN, or a load balancer) tried to contact your application server but got a bad or no response.

Common Causes

• Application server is down — Your Node.js/Python/PHP process crashed or isn't running
• App server not listening — Server is running but not bound to the expected port
• Firewall blocking traffic — Connection between proxy and app server is blocked
• App server overloaded — Too many requests, not enough workers
• Socket path mismatch — Nginx configured for wrong Unix socket path
• Container not running — Docker container stopped or failed to start

How to Debug

1. Is the app server running? — Check process status
2. Check app server logs — Did it crash? What's the error?
3. Verify port/socket — Is the app listening on the right port?
4. Test directly — Can you curl the app server directly (bypassing the proxy)?
5. Check proxy config — Is Nginx pointing to the right upstream?

Quick Checks

# Check if app is running
ps aux | grep node
systemctl status myapp

# Check if port is listening
ss -tlnp | grep 3000
netstat -tlnp | grep 3000

# Test app directly
curl http://localhost:3000/health

# Check Nginx logs
tail -f /var/log/nginx/error.log

Nginx Configuration Check

# Common upstream config
upstream app {
    server 127.0.0.1:3000;  # Make sure this matches your app
}

server {
    location / {
        proxy_pass http://app;
    }
}

Prevention

• Use a process manager (PM2, systemd) to auto-restart crashed apps
• Set up health checks in your load balancer
• Monitor your application server directly, not just the proxy
• Configure proper timeout and retry settings