504 Gateway Timeout: causes and how to fix it

02Which timeout fired? Mapping the timeout chain

Every hop in front of the application runs its own timers, and the first one to expire decides who returns the 504. The defaults below are the documented ones; your configuration may differ.

Two details cause most confusion. nginx's read timeout applies between two successive reads, not to the whole response, so a streaming response that sends data every 30 seconds never trips a 60-second limit while a page that computes silently for 61 seconds always does. And on Linux, in the usual non-thread-safe builds, PHP's 30-second max_execution_time does not count time spent waiting on system calls, streams or database queries, so a script blocked on a slow query can run past nginx's 60 seconds and the visitor gets a 504 although PHP's own limit looks shorter.

03What the logs say when the timeout fires

nginx records which phase timed out, and the two phases point to different causes. Both lines below were reproduced on nginx 1.22.1, one against a backend that sleeps before answering and one against a backend whose listen queue was full.

"While reading response header" means the application accepted the request but is slow: a query, a lock, an external API call, or a worker pool so busy that requests queue inside it. "While connecting" means the TCP connection never completed: a firewall silently dropping packets, a host that is down, or an application that has stopped accepting connections so its listen queue is full.

PHP-FPM logs its side too: "server reached pm.max_children setting" means every worker was busy and new requests waited, and "executing too slow" means a request passed request_slowlog_timeout, with its stack trace written to the slowlog file.

# the upstream accepted the request but sent no response headers in time
upstream timed out (110: Connection timed out) while reading response header from upstream

# the TCP connection to the upstream was never established
upstream timed out (110: Connection timed out) while connecting to upstream

04How to find the slow part

Time the same request at each hop with curl's timing variables. The gap between connect and first byte is time spent inside the upstream; a slow connect points at the network or a full listen queue.

If the first-byte time is just as long when you hit the application directly, the proxies are innocent and the application needs profiling. Turn on the database slow query log (MySQL's long_query_time defaults to 10 seconds, too high for web requests) and PHP-FPM's request_slowlog_timeout, which writes a stack trace for any request that runs longer than the value you set.

# from outside, through the CDN
curl -s -o /dev/null -w 'connect %{time_connect}s  tls %{time_appconnect}s  first byte %{time_starttransfer}s  total %{time_total}s\n' https://example.com/slow-page

# directly at the application, skipping every proxy
curl -s -o /dev/null -w 'connect %{time_connect}s  first byte %{time_starttransfer}s\n' -H 'Host: example.com' http://127.0.0.1:8000/slow-page

# is the application accepting connections? On a LISTEN socket, Recv-Q above Send-Q means a full queue
ss -ltn 'sport = :8000'
nstat -az TcpExtListenOverflows TcpExtListenDrops

05How to fix a 504 properly

Raising a timeout is sometimes right, for one endpoint that is legitimately slow. As a global fix it only makes visitors wait longer for the same failure and lets slow requests pile up and hold workers.

• Fix slow queries first: add the missing index, remove the N+1 loop, or cache the result
• Move long jobs off the request: accept the export or import, return 202 Accepted with a job ID, and let the browser poll for the result
• Give the worker pool real capacity: if PHP-FPM logs that it reached pm.max_children, add workers that fit in memory or make each request faster
• Set a longer timeout only on the endpoint that needs it, never server-wide
• Stream long responses, so data keeps flowing within the read timeout
• Keep each layer's timeout slightly shorter than the layer in front of it

location / {
    proxy_pass http://app;
    proxy_connect_timeout 5s;    # TCP connect to the upstream
    proxy_send_timeout    30s;   # gap between two writes to the upstream
    proxy_read_timeout    30s;   # gap between two reads from the upstream
}

# one known slow endpoint gets a longer budget, not the whole site
location /reports/export {
    proxy_pass http://app;
    proxy_read_timeout 300s;
}

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_read_timeout 60s;
}

06Keepalive and idle timeouts that do not line up

A connection between two layers has an idle timer at each end. If the layer in front keeps a connection open longer than the layer behind it, it will eventually send a request on a connection the other side is closing, which usually shows up as a 502. The mirror case produces 504s: a balancer whose idle timeout is shorter than the time the application needs before its first byte will cut off every slow request, however healthy the application is.

AWS states both halves for its Application Load Balancer: the idle timeout defaults to 60 seconds, a target that does not respond within it produces a 504, and the application's own keep-alive timeout should be longer than the balancer's. The same rule holds for any chain of proxies.

07504s behind a CDN, load balancer or WAF

Behind an edge provider, the provider's timeout is usually the outermost one. Cloudflare, as one documented example, returns its own error 524 when the origin accepts the connection but sends no response within its proxy read timeout, 125 seconds by default according to its documentation, and recommends status polling for long processes. Other providers have equivalent limits under their own codes.

A connect-phase timeout from the edge often means the origin firewall drops the edge's packets instead of rejecting them. Dropping makes the edge wait out its connect timeout; rejecting would have produced an instant refused connection and a 502. Either way, allow the provider's ranges, as described in how to hide and protect the origin.

Under attack, rising 504s are a common early symptom. An HTTP flood or a Slowloris attack ties up workers and connection slots until legitimate requests queue past every timeout. That is a capacity problem at the origin, and the durable fix is to filter the traffic before it arrives, together with sensible rate limiting on expensive endpoints.

08504 troubleshooting matrix