Nginx 502/504 Troubleshooting: A Field Engineer's Checklist

When your upstream returns 502 or 504, here's the systematic approach I use.

The Two Error Codes

Code Meaning Typical Cause
502 Bad Gateway Nginx can't reach upstream Upstream down, wrong port, firewall
504 Gateway Timeout Upstream too slow Heavy query, connection pool full

Step 1: Check the Error Log First 

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

Look for strings like:

  • upstream prematurely closed connection
  • connect() failed (111: Connection refused)
  • upstream timed out (110: Connection timed out)

Step 2: Verify Upstream is Alive 

# Check if upstream process is running ps aux | grep [n]ginx ps aux | grep [p]hp-fpm # Check listening ports sudo ss -tlnp | grep :80 sudo ss -tlnp | grep :9000

Step 3: Test Upstream Directly

Bypass Nginx and test the backend directly:

# Test PHP-FPM curl -I http://127.0.0.1:9000 # Test upstream application curl -v http://127.0.0.1:3000/health

Common Fixes

Issue 1: PHP-FPM Worker Exhaustion 

# Check worker count sudo systemctl status php8.2-fpm # Restart if needed sudo systemctl restart php8.2-fpm

Issue 2: Upstream Timeout Too Short 

# In nginx.conf location / { proxy_connect_timeout 60s; proxy_read_timeout 300s; proxy_send_timeout 60s; }

Issue 3: Firewall Blocking 

# Check firewall rules sudo iptables -L -n | grep 80 sudo ufw status

Prevention Checklist

  • [ ] Monitor upstream health with Prometheus
  • [ ] Set up alerting for 5xx errors
  • [ ] Regular log rotation and cleanup
  • [ ] Load testing before traffic spikes

More ops guides: ops.jiunotes.top