Nginx 502 Bad Gateway: A Production Troubleshooting Guide
Diagnose Nginx 502 errors by checking upstream availability, PHP-FPM, sockets, timeouts, resources and recent deployments.
A 502 means the proxy could not obtain a valid response from its upstream. The fastest path to the cause is to inspect the Nginx error log, upstream service state and system resources in the same time window.
Check the Nginx error log first
Look for connect failures, upstream timeouts, reset connections and socket errors. The exact error usually narrows the problem to a process, network path or timeout boundary.
Verify PHP-FPM or the upstream service
Check whether the upstream process is running and accepting connections. For Unix sockets, verify the socket path and permissions. For TCP upstreams, verify that the expected port is listening.
- systemctl status php-fpm or the relevant service
- ss -lntp for TCP listeners
- Check Unix socket existence and permissions
- Review application logs at the same timestamp
Check resource exhaustion
High load, exhausted memory, swap activity, full disks and process limits can make a healthy service appear unavailable. Compare the incident timestamp with server metrics rather than troubleshooting the proxy in isolation.
Check recent changes
A deployment, PHP configuration change, certificate rotation or infrastructure migration may explain a sudden 502. Use monitoring history to correlate the first failures with changes.
Prevent recurring 502 incidents
External endpoint monitoring can alert on the user-visible failure while server monitoring identifies the underlying resource or service condition. Together they shorten the path from alert to root cause.
Monitor endpoints before users report 502 errors
Connect your infrastructure, receive telemetry and investigate incidents from one Shell Guard account.