Originally published at hamzaahmadaslam.com.
How this article was made: drafted with AI assistance from a researched brief, then checked against primary documentation before publishing.
A WordPress 504 gateway timeout means a gateway or proxy timed out while connecting to an upstream, sending it a request, or waiting for its response. Start by recording one failing request with an exact timestamp and timezone, then trace that same request through the edge, web proxy and PHP logs. A WordPress 502 bad gateway needs the same path, but HTTP defines it as an invalid upstream response rather than a response that arrived too late.
What a WordPress 504 gateway timeout proves, and what it does not
HTTP 502 and 504 describe what a gateway saw while talking to another server. RFC 9110 defines 502 as an invalid response from an inbound server, while 504 means the gateway did not receive a timely response from an upstream server.
That tells you where to start, not what caused the incident. The slow or unavailable upstream might be PHP-FPM, another web server, a service behind a CDN, or a dependency reached while PHP handles the request.
On Nginx with PHP-FPM, three waits matter. fastcgi_connect_timeout covers establishing the FastCGI connection. fastcgi_send_timeout covers the interval between successive writes while Nginx transmits the request. fastcgi_read_timeout covers the interval between successive reads from FastCGI.
The Nginx FastCGI documentation lists a 60-second default for all three directives, but your host can override them. The send and read values are inactivity intervals between write or read operations, not whole-request deadlines.
When one of these upstream timeout failures becomes the final response, Nginx maps it to 504. The Nginx error log tells you which stage timed out:
-
while connecting to upstreammeans Nginx did not establish the upstream connection. -
while sending request to upstreammeans the connection was established, but Nginx could not finish transmitting the request. -
while reading response header from upstreammeans Nginx established the connection and finished sending enough to wait for the response header.
The last two cases prove a connection existed. They do not prove a PHP-FPM worker had started the request. A connected socket can still wait in PHP-FPM's listen backlog while all workers are busy.
Connection refusal, a missing Unix socket, or no live upstream is a different path and normally becomes 502 if that failure is final. One Linux Unix-socket case needs separate treatment: a full listen queue can make connect() fail with EAGAIN, logged as Resource temporarily unavailable, and Nginx then returns 502. That points to FPM capacity pressure rather than a stopped service.
Identify which layer emitted the status
Write the request path as a chain before changing anything:
browser → CDN or edge → reverse proxy → PHP-FPM → WordPress → database or remote service
Start with the outermost layer whose logs you can access. Find the exact request and establish two facts: which layer returned the 502 or 504 downstream, and what happened when that layer contacted its upstream.
If you use Cloudflare, its current 502 and 504 troubleshooting documentation separates errors returned by the origin from errors generated by Cloudflare. It also asks for the failing URL plus a timestamp with timezone when escalating an incident. Other edge providers expose different fields, so use that provider's current documentation.
For an Nginx origin, request-level timing fields are more useful than the error page. Nginx documents $upstream_connect_time, $upstream_header_time, $upstream_response_time and $upstream_status in its upstream module reference.
Use the fields your host already records. If a self-managed Nginx server does not record them, add incident logging through your normal configuration review and rollback process rather than editing production blindly.
| Evidence for the same request | Expected interpretation |
|---|---|
| Edge returns 504, but the origin proxy has no matching request | Check the edge-to-origin path or the edge itself before investigating WordPress |
| Nginx returns 502 after connection refusal, a missing socket or no live upstream | Treat the upstream as unavailable for that attempt, unless a Unix socket reports Resource temporarily unavailable
|
Nginx returns 502 with (11: Resource temporarily unavailable) while connecting to a PHP-FPM Unix socket |
The FPM listen queue was full; treat this as capacity saturation rather than an unavailable service |
Nginx returns 504 with while connecting to upstream
|
The connection was not established; investigate the upstream connection path and capacity before application code |
Nginx returns 504 with while sending request to upstream
|
Nginx connected but stalled while transmitting the request; a PHP worker may still not have accepted it |
Nginx returns 504 with while reading response header from upstream
|
Nginx connected and waited for a response header; check FPM queueing before assuming WordPress code was already running |
Completed FPM row has %t after the proxy's 504 and a short %d
|
The request likely waited for a free FPM worker; check pool saturation rather than treating the route itself as slow |
Completed FPM row starts before the proxy timeout and finishes after it, with %d spanning the wait |
PHP work outlasted the proxy; investigate what kept that request running |
| PHP finishes before the outer layer times out or answers | Inspect the proxy or edge path after PHP before blaming PHP execution time |
Use the Nginx error-log phrase together with $upstream_connect_time and $upstream_header_time when those fields are available. $upstream_connect_time records time spent establishing the upstream connection. $upstream_header_time records time spent receiving the response header.
Treat a missing PHP access-log row carefully. PHP-FPM writes its access row when the request finishes. %t is based on the time an FPM worker accepts and starts reading the request, while %T records when the access log is written at request end.
A row can therefore be absent because PHP-FPM access logging is disabled, retention removed it, the request is still executing, or every worker is busy and the connection is still queued. A worker killed by request_terminate_timeout, or a similar process limit, may also end without the normal access row being written.
Before concluding that PHP never received a request, check the PHP-FPM error log for an execution timed out ... terminating warning. If request_slowlog_timeout and the slowlog are enabled, check the same time window there as well. Pair that evidence with Nginx's connection, send or read-stage error message.
Run one controlled failing request
Choose one request that already fails reliably. The goal is to reproduce the incident once under controlled conditions, not to create a new failure.
Use a read-only request when possible. If the failure happens during an action that changes data, reproduce it in staging or use a safe test path approved for that system.
Record these fields before pressing the button or sending the request:
- Write the exact local time and timezone.
- Record the HTTP method and path, such as the admin URL or endpoint that fails.
- Record the account state that matters, such as logged-in admin versus logged-out visitor.
- Record the response status and the time the response ends.
- Save any provider request identifier that already exists in the response or dashboard.
Do not restart PHP, purge every cache, disable all plugins or change timeout values before collecting the first timeline. Those changes can remove the state you need to explain the failure.
If the dashboard times out while public pages still work, trace the exact dashboard request first. A cached public page can succeed without exercising the PHP path that handles the admin request.
Correlate request timestamps with a worksheet
Use one timezone across every row. If a tool logs in another timezone, convert it before comparing events. Keep the original value in your incident notes.
PHP-FPM can provide application-side request evidence without adding logging code to WordPress. Its configuration manual documents access.log and access.format. The format can record worker acceptance time, log-write time, duration, method, URI and response status. access.log is not set by default, so confirm that your host collects equivalent request data before relying on it.
Remember that the access line is written at request end. Also allow for queueing before %t: Nginx can establish a connection before an FPM worker accepts it.
Copy this worksheet for the failing request:
| Stage | Timestamp | Request evidence | Status or timing | What this row proves |
|---|---|---|---|---|
| Client | <time + timezone> |
<method> <path> |
<status>, <end time>
|
The exact failure the user received |
| Edge, if present | <time> |
<edge request ID or method/path> |
<edge status>, <origin status if available>
|
Whether the edge passed through or emitted the error |
| Nginx or other origin proxy | <time> |
<method/path> |
<final status>, <connect/header/response timings>, <error-log action>
|
Whether connection, request transmission or response reading stalled |
| PHP-FPM access log, for completed requests | <%t worker acceptance time> |
<method/path> |
<%T log-write time>, <%d duration>, <status>
|
When a worker picked up and completed the request |
| PHP-FPM error or slow log | <time> |
<matching route or worker> |
<termination warning or slow backtrace> |
Whether a worker was executing slow work even when the normal access row is absent |
| FPM or host capacity view | <same and following window> |
<TCP queue, Unix-socket queue, active/total processes, worker state> |
<capacity state> |
Whether the connection waited for an available worker |
| WordPress or PHP error log | <time> |
<matching route or process> |
<error, warning or matching event> |
Whether application code recorded a failure near the request |
Do not require %t to fall inside the proxy's original request window. Under saturation, Nginx can connect while every FPM worker is busy. The listen backlog can hold connections until a worker accepts them.
From PHP 8.2 onward, PHP-FPM's default listen.backlog is -1 on Linux. Current PHP source uses that value to request the platform maximum. On Linux, the kernel caps the backlog at /proc/sys/net/core/somaxconn.
A pool can also set listen.backlog explicitly. Read the running configuration rather than assuming a fixed queue size.
The FPM status page needs another caveat. Its listen queue, max listen queue and listen queue len values are populated from the listening socket only for TCP listeners in current PHP-FPM source. For a Unix-socket listener, those queue fields remain zero even when connections are waiting.
On Linux with a Unix-socket pool, inspect the listening socket directly:
ss -xlp
On the matching LISTEN row, Recv-Q is the number of connections waiting to be accepted and Send-Q is the backlog limit. Use that evidence with the pool state rather than using the FPM status page's Unix-socket queue value.
For a TCP FPM listener, the status page queue fields can provide queue evidence. For either listener type, compare active processes, total processes and the configured pm.max_children.
Dynamic pools log server reached pm.max_children setting when that limit is reached. Ondemand pools use server reached max_children setting instead. If your log search accepts regular expressions, search for reached.*max_children to catch both forms.
Static pools emit neither warning and do not increment the status page's max children reached counter. For a static pool, compare active processes with total processes and pm.max_children, then combine that with Nginx or socket-queue evidence.
If %t appears after the Nginx 504 and %d is short, the missing time happened before the worker accepted the request. For a TCP pool, check the FPM status queue fields. For a Linux Unix-socket pool, use ss -xlp instead.
A slow-or-queued upstream scenario can look like this: Nginx connects near T0, finishes sending the request, then logs while reading response header from upstream and returns 504 at T1.
If an FPM worker was free, the completed access row may later show %t near T0. If every worker was occupied, %t can be much later and can even fall after T1. A late %t combined with a short %d points to listen-backlog queueing rather than slow application execution.
If the request is still executing at T1, the FPM access row does not exist yet at that point. Check the slowlog and FPM capacity evidence before deciding which delay occurred.
A send-timeout scenario can look like this: Nginx connects, then logs while sending request to upstream and returns 504. Expected interpretation: the connection existed, but Nginx could not finish passing the request upstream within the effective send timeout.
This case can matter for a large POST or upload when the receiving side is not consuming data. It does not prove an FPM worker started executing WordPress.
An unavailable-upstream scenario can look like this: Nginx returns 502 after a refused connection, missing socket or no-live-upstream condition. Another unreachable case can return 504: Nginx logs while connecting to upstream because the connection attempt itself timed out.
On Linux with a PHP-FPM Unix socket, check for (11: Resource temporarily unavailable) before calling a 502 an unavailable service. Nginx's source documents that Linux can return EAGAIN when the Unix-socket listen queue is full.
When several identical requests happen close together, do one controlled reproduction at a known time rather than matching on the path alone. If your stack already supplies a request ID, use it across every layer that preserves it.
Check upstream waits and saturation separately
A slow upstream and an unavailable upstream call for different fixes.
For a refused connection, missing socket, no-live-upstream error, or a 504 logged while connecting to upstream, check PHP-FPM service health, socket or network reachability, recent deploy changes and host events. Capacity can also block connection establishment, so compare the event with the host's PHP queue and worker evidence.
For a Unix-socket 502 with Resource temporarily unavailable, start with FPM capacity. The Linux-specific Nginx path associates that EAGAIN result with a full Unix-socket listen queue.
For a timeout while sending request to upstream, investigate why Nginx could not continue writing the FastCGI request. Check FPM saturation before assuming PHP application code caused the stall.
For a timeout while reading response header from upstream, a connection existed, but a worker may still have been waiting to accept it. For TCP listeners, check the FPM status queue fields. For Linux Unix-socket listeners, use ss -xlp because the FPM status queue fields do not report that queue.
Also compare active processes and total processes with pm.max_children. For dynamic and ondemand pools, check the matching max_children warning or counter. For static pools, rely on the process counts plus proxy or socket-queue evidence because the warning and counter are not produced.
Once %t shows that a worker accepted the request, use %d, %T, application logs and traces to separate slow execution from earlier queueing. If %t precedes the proxy 504 and %T follows it, compare %d with the effective proxy or edge read wait.
PHP can keep executing after the downstream connection disappears until it detects the disconnect during output, unless its connection-handling settings or code change that behavior. WordPress commonly produces buffered responses, so an FPM access row can show a normal application status after Nginx has already returned 504.
That later normal PHP status does not clear PHP execution. If %d shows that PHP ran beyond the outer layer's effective wait, investigate the slow request. Inspect proxy or edge handling first when PHP finished before that outer layer timed out or answered.
PHP-FPM's pm.max_children sets the limit on simultaneous requests the pool can serve. If your host exposes worker or queue metrics, compare them with the failure window and the period immediately after it.
Do not raise worker counts or proxy waits from one 504 alone. A larger wait may make the same slow request occupy capacity for longer, and a larger worker pool must fit the server's memory and workload.
If application traces point to a remote call made through the WordPress HTTP API, WordPress builds the request's default timeout from five seconds through the http_request_timeout filter. A caller can pass its own timeout, but that still may not be the effective value.
Code attached to http_request_timeout can change the default used when the caller does not supply one. After WordPress parses the request arguments, the http_request_args filter can rewrite them, including an explicit timeout. To find the effective value, check the call's arguments and callbacks attached to both filters.
Use host and PHP logs for a production incident before enabling WordPress debug tools. WordPress's current debugging guide says those tools are intended for local testing and staging installs.
Pinpoint a dashboard-only timeout
Start with the request that the browser shows as failed in the dashboard. Record its method, path, start time and response status, then find that same request in the proxy and PHP records.
Next, compare it with another dynamic request from the same period that your host confirms reaches PHP. Public page success by itself is weak evidence because a cache may answer that request before PHP runs.
If an admin request has a long %d after a worker accepts it, inspect the code path tied to that route. If %t appears late while %d stays short, check pool saturation instead. If many dynamic routes queue or time out together, check PHP capacity and upstream health first.
If Nginx logs while connecting to upstream, application profiling will not explain that event because the FastCGI connection was never established. A while sending request to upstream or while reading response header from upstream message proves a connection existed, but you still need FPM evidence to establish when a worker accepted the request.
This approach also handles a production-only WordPress 504 error. Keep the failing production timeline, then reproduce the same safe route in staging only after you know which layer to inspect.
Validate recovery with the same request
Apply one fix that matches the evidence. Examples include restoring an unavailable PHP upstream, correcting a broken proxy-to-FPM path, removing slow work from the request, or resolving a capacity problem.
Then run the same single safe request again under comparable application conditions. Record a second timeline in the same worksheet.
The expected result is that the outer layer returns the application's intended status and the proxy reaches the expected upstream. For PHP requests, compare the new connection timing, FPM worker acceptance time and execution duration with the failing timeline.
For a saturation incident, do not deliberately recreate incident-level traffic against the live site. Run the single safe production request, then watch the same worker, queue and proxy evidence during the next natural traffic window of similar size.
If deliberate load reproduction is needed, run it in staging or during an approved, monitored maintenance window where the production risk has been accepted. Do not generate outage-level load against normal live traffic.
One successful refresh does not settle an intermittent incident. Keep watching the same route, status codes and capacity evidence during normal traffic that resembles the earlier failure window.
Take the next diagnostic step
If the worksheet points to a full PHP pool or long request queue, continue with WordPress PHP workers: size them, spot saturation and use fewer instead of changing a timeout. If the failing request is checkout, use the guide to diagnosing a slow WooCommerce checkout request after you have isolated the application layer.
If storage pressure is stopping logs or application writes, move to finding what is filling a WordPress site's disk. For ongoing incident ownership, WordPress maintenance and security covers the operational work around keeping the site healthy.
Top comments (0)