nginx Troubleshooting

nginx as web server, proxy, and gateway

nginx can serve static files, pass requests to PHP-FPM, proxy to an app server, sit behind a CDN, or front multiple upstreams. A visible nginx error is a clue, not a complete diagnosis. Start with the error log, then match it to the configured server block, location, upstream, socket, or proxy_pass target.

Commands to verify safely

nginx -t
systemctl status nginx
systemctl status php-fpm
curl -I http://127.0.0.1:3000/

Run config validation before reloads. If a production service is managed by a panel, container orchestrator, or host, use the equivalent health screen rather than restarting blindly.

Rollback and escalation

For changes to server blocks, upstream names, sockets, or proxy_pass, keep the previous file and reload only after nginx -t succeeds. Escalate with the exact log phrase, upstream target, changed config file, and timestamp.

Layer quick reference

proxy_pass sends HTTP traffic to another service. fastcgi_pass sends PHP requests to PHP-FPM. A named upstream block can hold multiple backends. A Unix socket is a local file-like endpoint, while a TCP upstream uses host and port. When a route breaks, verify the exact directive used by that location block rather than assuming every nginx 502 is PHP-FPM.

What not to do first

Do not increase timeouts before you know whether the upstream is reachable. Longer timeouts can hide an outage and make users wait longer. Confirm service health, socket path, port, and logs first, then adjust timeout settings only when the upstream is healthy but legitimately slow.