Nginx 502 bad gateway: how to find what is failing

The browser only says 502. The Nginx error log says why. On most Linux servers it sits at /var/log/nginx/error.log. Run tail -f on it, reload the page and read the line that appears.

That line carries the upstream address and a reason in brackets. Connection refused, No such file or directory, Connection reset by peer and upstream sent too big header each point to a different fix. Guessing before reading wastes an afternoon. Read first.

Often the application is simply down. Ask the process manager. Run systemctl status for the service, or pm2 list if the app runs under PM2, or docker ps for a container.

Look at why it stopped. Never skip this. An out of memory kill leaves a trace in journalctl and dmesg. A crash on boot, often a missing environment variable after a deploy, shows in the application log.

Restart it. Then watch whether it stays up for an hour, since a service that restarts every few minutes produces intermittent 502s that vanish by the time you look..

Open the server block and find proxy_pass or fastcgi_pass. The address there must be the one the app listens on. A deploy that moved the app from port 3000 to 3001 breaks the site until someone edits this line.

Test from the server itself. Run curl against the upstream address directly. If curl works and the site does not, the fault is inside Nginx. If curl fails, the fault is the app.

For PHP-FPM, check the socket file exists and that the Nginx user may read it. Permission denied on a socket looks identical to a dead service from outside.

Intermittent 502s usually come from limits. Worker processes in PHP-FPM run out, a Node process runs out of memory or a database pool fills up and requests stall until the app gives up.

Large response headers cause a quieter version. A framework that sets several big cookies can exceed proxy_buffer_size, and Nginx drops the response. Raise the buffers modestly rather than to huge values.

Compare timestamps. Be patient. Match the error log entries against the application log and the traffic spike. The pattern usually names the cause.

A 502 says the upstream answered badly or not at all. A 504 says the upstream took too long and Nginx stopped waiting. The first points to crashes and addresses. The second does not. The second points to slow queries, long reports and proxy_read_timeout.

Do not raise timeouts as a first reaction. It hides the cause. A report that needs ten minutes belongs in a background job with a progress screen.

Keep a short runbook with the log path, the service name and the five commands above, so the next incident takes minutes.