How do I diagnose a 502 Bad Gateway response from Nginx?
A 502 response commonly means a proxy could not obtain a usable response from its upstream. The upstream may be down, listening elsewhere, using a different protocol or closing the connection unexpectedly. Identify the exact upstream for the failing route; the public web server can be healthy while its application dependency fails.
Before you start
- Access to the site’s configured upstream and error log.
- The actual upstream port or UNIX socket.
Instructions
1. Read the matching proxy error
Correlate the failing URL and timestamp with the site’s error log. Distinguish connection refusal, permission denial and an invalid upstream response before choosing a fix.
sudo tail -n 60 /var/log/nginx/error.logUses a common example log path; substitute the active site log.
2. Inspect the actual upstream listener
The example assumes an HTTP application on local TCP 8080. Replace it with the verified upstream. PHP-FPM often uses a UNIX socket or FastCGI port instead.
sudo ss -lntp 'sport = :8080'Checks whether a process listens on the example application port.
3. Test using the upstream protocol
For an HTTP upstream only, make a safe local request. Do not send an HTTP curl request to a PHP-FPM FastCGI socket and interpret that failure as a broken service.
curl --head --connect-timeout 3 --max-time 10 http://127.0.0.1:8080/Checks the example local HTTP upstream without passing through the public reverse proxy.
Check the result
- The configured upstream is reachable using the correct protocol and the original public request returns its expected response.
Troubleshooting
- The upstream works locally but Nginx still fails
- Compare the configured address, port, Host behaviour, socket permissions and applicable SELinux policy. The proxy worker may not have the same access as your login account.
Official references
Use the documentation for your installed version when a flag, service name or platform feature differs.