Troubleshoot 504 Gateway Timeout responses from an Nginx proxy

A 504 means a gateway did not receive a timely upstream response. If Nginx generated it, its error log usually identifies whether the timeout occurred while connecting, sending a request, or reading the response. It does not prove the backend process is alive, and a 504 can also arrive from a gateway upstream of Nginx.

Identify the timeout phase

Inspect the error at the request's timestamp and compare it with the access log. For an HTTP upstream, an illustrative location is:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_connect_timeout 60s;
    proxy_send_timeout 120s;
    proxy_read_timeout 120s;
}

Choose values from the service's latency and deadline requirements; these are not universal fixes.

The send and read settings do not cap the entire request duration. A response that keeps producing data within the read interval can last longer. A configured connection timeout is also subject to underlying operating-system behavior.

For PHP-FPM or another FastCGI backend, the analogous settings are fastcgi_*; HTTP proxy directives do not control that path.

Investigate from the proxy's network context

curl -v --connect-timeout 5 --max-time 15 http://127.0.0.1:8080/health
sudo tail -50 /var/log/nginx/error.log
tail -50 /var/log/app/app.log

Replace the loopback endpoint with the actual upstream and run from the same host or container network. A healthy /health endpoint does not demonstrate that the failing report or API query is fast. Check whether the actual request reached the application, then examine database latency, connection pools, worker saturation, downstream calls, and runtime pauses.

Record request and upstream timing fields before relying on them. Collected traces can identify slow instrumented spans, and shared trace IDs can connect application logs; they cannot reveal uninstrumented work automatically. Guance's Nginx integration provides a starting point for collecting the proxy's own evidence.

Choose a bounded operational change

Give a genuinely slow route a separate timeout rather than raising every endpoint to several minutes. For long exports and batch jobs, an asynchronous job with polling or completion notification often avoids holding a request open across every intermediary.

Check load-balancer, CDN, application, and downstream deadlines together. Making Nginx wait longer cannot override an earlier component's shorter deadline. For pools of upstreams, examine passive failure handling and retry policy; active health-check capabilities depend on the Nginx product and modules in use. Avoid replaying non-idempotent requests without a deliberate policy.

FAQ

Why did the status become 502 after increasing the timeout?

The upstream may now close the connection before Nginx's longer deadline, or a different failure may be visible. A 502 can also result from connection refusal or an invalid response. Read the new error rather than assuming the backend crashed.

Is a five-minute read timeout ever acceptable?

It can be appropriate for a deliberately designed workflow, but account for connection capacity, client deadlines, cancellation, and every proxy in the path. Prefer an asynchronous contract when the client need not keep a connection open.

How do I distinguish 502 and 504?

Treat them as different gateway failure categories, then use the exact log cause. Neither status alone establishes whether the upstream was alive or how far request processing progressed.

Reference: Nginx proxy timeout directives.