DEV Community

Yash
Yash

Posted on

How to Fix 502 Bad Gateway in Nginx (With Exact Commands)

#devops #nginx #linux #webdev

How to Fix 502 Bad Gateway in Nginx (With Exact Commands)

502 Bad Gateway is one of the most panic-inducing errors in production. Your site is down, users are getting errors, and you have no idea where to start.

This guide gives you the exact diagnostic steps and fixes — no placeholder commands.

What Does 502 Bad Gateway Actually Mean?

Nginx received a bad response (or no response) from the upstream server. Nginx itself is fine. Something behind Nginx is broken.

Common culprits:

  • Your Node.js/Python/PHP app has crashed
  • Wrong upstream port configured
  • App is binding to localhost but Nginx is trying 127.0.0.1 (or vice versa)
  • App is overloaded and not responding in time

Step 1: Check If Nginx Is Actually Running 

systemctl status nginx
Enter fullscreen mode Exit fullscreen mode

If it's active, Nginx is fine. Move to step 2.

If it's dead:

nginx -t
systemctl restart nginx
Enter fullscreen mode Exit fullscreen mode

Step 2: Check Your Upstream App 

curl -I http://127.0.0.1:3000
Enter fullscreen mode Exit fullscreen mode

Replace 3000 with your app's port. If you get Connection refused, your app is down — not Nginx.

Step 3: Read the Error Logs 

tail -100 /var/log/nginx/error.log
Enter fullscreen mode Exit fullscreen mode

Look for: connect() failed, upstream timed out, no live upstreams.

Step 4: Restart Your App Process 

# PM2
pm2 restart all
pm2 logs --lines 50

# Systemd
systemctl restart myapp
journalctl -u myapp -n 50 --no-pager

# Docker
docker ps -a
docker restart my-container
docker logs my-container --tail 50
Enter fullscreen mode Exit fullscreen mode

Step 5: Fix Common nginx.conf Issues 

upstream backend {
    server 127.0.0.1:3000;  # Use IP, not 'localhost'
    keepalive 32;
}

server {
    location / {
        proxy_pass http://backend;
        proxy_read_timeout 90s;   # Add this if timing out
        proxy_connect_timeout 10s;
    }
}
Enter fullscreen mode Exit fullscreen mode

After editing:

nginx -t && systemctl reload nginx
Enter fullscreen mode Exit fullscreen mode

Step 6: If App Keeps Crashing 

# Check memory
free -h

# Check disk space (full disk = crash)
df -h

# Check CPU
top -bn1 | head -20
Enter fullscreen mode Exit fullscreen mode

Quick Decision Tree 

502 Error
├── curl 127.0.0.1:PORT → Connection refused?
│   └── App is down → Check app logs → Restart app
├── curl works fine?
│   └── Nginx config issue → Check proxy_pass → nginx -t
└── Intermittent 502?
    └── App overloaded → Add proxy_read_timeout → Scale up
Enter fullscreen mode Exit fullscreen mode

Most Common Root Causes (from real production issues)

  1. App crashed due to unhandled promise rejection — add process.on('unhandledRejection')
  2. Port mismatch — app on 3001 but Nginx pointing to 3000
  3. App bound to 0.0.0.0 but Nginx using localhost — use 127.0.0.1 everywhere
  4. Memory exhaustion — app OOM killed, use pm2 restart --max-memory-restart 512M

Debugging production errors at 3AM shouldn't take hours. Step2Dev — paste your error, get the exact fix for your infra in 60 seconds. No generic answers.

Top comments (0)