Troubleshoot 502 Bad Gateway errors in Nginx

A 502 Bad Gateway response means Nginx could not obtain a valid response from an upstream server. The cause may be a stopped application, a reset connection, a protocol mismatch, or incorrect proxy settings. It does not prove that Nginx's configuration is correct.

Start with the error log for the failed request, then check the backend address from the same host or network namespace as Nginx.

Confirm that both services are running

On a systemd host, substitute the real application service name:

sudo systemctl status nginx
sudo systemctl status php-fpm
sudo ss -ltnp | grep -E '9000|8080|3000'
sudo tail -50 /var/log/nginx/error.log

If the backend stopped, inspect its logs and restart it through its service manager. A restart may restore service while leaving a crash or memory problem unresolved.

Check the upstream endpoint

location / {
    proxy_pass http://127.0.0.1:8080;
}

The address, port, and protocol must match the backend. Inside a container, 127.0.0.1 refers to that container's network namespace, not automatically to another container. For fastcgi_pass unix:/run/php-fpm.sock;, verify that the socket exists and that Nginx can traverse the directories and connect to it.

Let the error message guide the fix

Do not blindly disable SELinux or change a network-connect boolean for a Unix-socket error. Inspect the relevant denial and apply a policy or permission change appropriate to the actual connection.

Across several proxies, compare the same time window, host, request path, and upstream address. The Guance Nginx integration provides a starting point for collecting logs; verify parsed fields before using them to correlate failures.

Adjust timeouts only when the evidence supports it

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_connect_timeout 10s;
    proxy_read_timeout 60s;
    proxy_send_timeout 60s;
}

The read and send settings limit gaps between successive operations, not the total request duration. Larger values will not fix a dead process or wrong port.

sudo nginx -t && sudo systemctl reload nginx

FAQ

Why does an occasional 502 disappear by itself?

Look for backend restarts, exhausted connection pools, and overloaded workers at that time. Intermittence is a reason to correlate logs, not proof of a particular cause.

How does 502 differ from 504?

502 indicates a failed or invalid upstream response; 504 indicates an upstream timeout. A 504 can occur while establishing a connection as well as while waiting for response data.

Why do only some requests fail behind a load balancer?

One member may be unhealthy. Review max_fails and fail_timeout for passive failure handling, and remove or repair the failing member through your deployment process. Active health checks and their availability depend on the installed product and modules.

References: proxy directives, upstream failure handling.