P1
502 Bad Gateway — Nginx Troubleshooting Guide
Diagnose and fix Nginx 502 errors caused by unreachable or crashed backend services. Covers error log analysis, upstream health checks, and service recovery.
10 min7 steps
Progress: 0/7 steps
0%
Find the specific error causing the 502.
tail -30 /var/log/nginx/error.log | grep -i '502\|upstream\|connect'
Expected: Common: 'connect() failed (111: Connection refused)' means backend is down. 'no live upstreams' means all backends are unhealthy.
Verify the upstream application or service is alive.
ss -tlnp | grep :BACKEND_PORT
Expected: Backend should be LISTEN on its port. If nothing shows, the backend is down.
Bypass Nginx and hit the backend directly to confirm it responds.
curl -v http://127.0.0.1:BACKEND_PORT/
Expected: Should return a valid response. If it fails here too, the problem is the backend, not Nginx.
Verify the proxy_pass target matches the actual backend address.
nginx -T 2>/dev/null | grep -A5 'upstream\|proxy_pass'
Expected: proxy_pass URL should match the backend's listening address and port.
Restart the backend application or service.
systemctl restart BACKEND_SERVICE && sleep 3 && systemctl status BACKEND_SERVICE
Expected: Service should be 'active (running)'. Check with curl again.
Validate Nginx config syntax and reload.
nginx -t && systemctl reload nginx
Expected: 'syntax is ok' and 'test is successful'. Reload applies changes without downtime.
Test the endpoint through Nginx.
curl -I https://YOUR_DOMAIN/
Expected: HTTP status should be 200 (or expected response), not 502.