An Nginx 502 means the proxy could not obtain a valid response from its upstream. Capture the exact failure in the Nginx error log and test the upstream directly before increasing timeouts or restarting services.
Last updated: October 13, 2026.
# Test through Nginx, then test the upstream directly.
curl -sS -o /dev/null -w '%{http_code} %{time_total}\n' https://example.com/health
curl -sS -o /dev/null -w '%{http_code} %{time_total}\n' http://127.0.0.1:8080/health
# Correlate the same timestamp with proxy and application logs.
sudo tail -n 100 /var/log/nginx/error.logUse the real health route and upstream address from proxy_pass. If the direct request also fails, investigate the application or PHP-FPM service. If only the proxied request fails, compare Nginx routing, DNS, TLS, socket permissions, and headers.
Classify the error-log message
“Connection refused” usually means nothing is listening at the selected address or port. “No such file or directory” points to a missing Unix socket, and “Permission denied” points to socket or security-policy access. “Upstream timed out” means a connection was made but the upstream did not produce data within the configured interval.
The Nginx proxy module documentation defines proxy_connect_timeout for establishing a connection and proxy_read_timeout for the interval between upstream reads. They measure different phases, so changing both blindly can hide the real bottleneck.
Fix capacity and health before relaxing limits
Check application crashes, worker exhaustion, memory pressure, deployment restarts, database waits, and traffic spikes at the same timestamps. Graph 502 counts beside upstream latency and active-worker metrics so an intermittent failure is not reduced to one log line. For multiple upstreams, verify that health and retry behavior match whether requests are safe to repeat. Nginx documents load-balancer failure handling, but retries cannot repair a response that already started.
Raise a timeout only when the operation is expected to take longer and the upstream has enough capacity to hold those requests. Otherwise improve the slow operation, move long work to a background job, or return an asynchronous job identifier.
Continue with PHP socket timeouts, PHP execution time errors, and safe API retries.
