WordPress 504 error: hosting or site?

#What does a 504 error mean in WordPress?

MDN, citing RFC 9110, defines 504 as a situation in which a server acting as a gateway or proxy “did not get a response in time from the upstream server”. This differs from 502 Bad Gateway: there a response arrived, but it was invalid. With 504 nothing arrived.

On typical WordPress hosting the chain looks like this: browser, optionally a CDN, nginx, PHP-FPM, the database and possibly an object cache. The 504 is generated by the link that was waiting. That alone tells you where to look. If nginx is waiting for PHP, the problem lies in PHP, the database or the queue for PHP. If the CDN is waiting, the problem lies in the origin server.

The MDN documentation also notes that the causes are many and that fixing the problem usually requires analysis on the server administrator’s side. That is why there is no single magic fix below, only an order of checks.

#Is a 504 the hosting’s fault or the site’s?

The scope of the error decides it. The table below is a decision shortcut, not a verdict.

The hosting’s responsibility begins where the limits (number of workers, memory, CPU) are too small for the site’s normal traffic. The site’s responsibility begins where a single request does so much work that it blocks a worker for tens of seconds. In practice both often apply at once: slow requests occupy the workers, and a small pool has no slack.

#How do you check where the request got stuck?

Start with three places, in this order.

1. The web server error log from the time of the failure. In nginx, an upstream timed out entry confirms that the server was waiting for PHP.
2. The PHP-FPM log. A message about reaching pm.max_children means the pool was full and later requests stood in the queue. The pm.max_children option, as the PHP documentation describes it, sets the limit of simultaneous requests handled by the pool.
3. The WordPress log. In wp-config.php, set WP_DEBUG to true, WP_DEBUG_LOG to true and WP_DEBUG_DISPLAY to false. Errors go to wp-content/debug.log instead of the screen. This is how the WordPress documentation describes it. Turn debug off after the diagnosis.

If your host gives access to the PHP-FPM slow log, set request_slowlog_timeout, and PHP will write a backtrace of requests that last longer than the limit. By default the option is off (value 0). The backtrace shows in which plugin or theme function PHP was waiting.

On shared hosting you often have no access to these logs. In that case, access to them and to the PHP pool metrics is the first thing to ask support for, together with the time of the failure and the address that returned the 504.

#Why does a PHP-FPM pool that is too small cause a 504?

Every dynamic request occupies one PHP-FPM worker until the response is finished. When all workers are busy, new requests wait. If they wait longer than the proxy limit, the visitor sees a 504.

The default fastcgi_read_timeout in nginx is 60 seconds, and the nginx documentation notes that the limit is counted between two successive reads from the FastCGI server, not for the whole response. On managed hosting the value can differ, so do not assume that yours is exactly 60 seconds.

Raising pm.max_children helps only if the server has the memory for it. Each WordPress worker with a few plugins takes a noticeable chunk of it, so a value that is too high ends in exhausted RAM and killed processes, a worse state than a queue. Pool configuration is a job for an administrator who can see memory usage.

#How do slow queries and autoloaded options cause a 504?

When the 504 affects the whole site and the pool is not full from traffic, check the database. The WordPress documentation points out that WordPress repeats many queries on every request, and options flagged as autoload are loaded on every visit. It recommends keeping them below 800 KB, and the full recommendations are in the optimization guide. A plugin that stores large data in wp_options with autoload pushes it into every request. You can check the autoload size with an SQL query on the autoload column of the options table.

To track down slow queries, use the SAVEQUERIES constant. It records every query, its execution time and the function that called it in $wpdb->queries. It costs performance, so turn it on briefly and, if possible, on staging.

#When do the object cache and Redis cause a 504?

A persistent object cache reduces the number of database queries and usually speeds the site up. It does require a working cache server and the drop-in file wp-content/object-cache.php.

Failure works the other way round when that file exists but the Redis server does not respond. Every request then tries to connect to the cache, waits for the connection timeout and only then moves on or gives up. The symptom is a 504 right after a restart or a failure of the cache service on the host’s side, even though the site’s code has not changed.

The test is simple: rename object-cache.php to something else. If the 504 disappears, the cache is to blame, not WordPress. Restore the file only after the service is repaired.

#How do WP-Cron, admin-ajax and external APIs cause a 504?

Three sources of single, slow requests are worth checking separately.

• WP-Cron. The WordPress documentation explains that WP-Cron runs when a page is visited, not as a permanent process. Overdue, heavy tasks (backups, imports, mailings) can therefore load an ordinary visitor request. Moving the calls to the host’s system cron relieves the front end.
• admin-ajax.php. Plugins send requests here from the dashboard and from the front end. If the 504 appears exactly here, look for a plugin that performs a heavy operation in the background.
• External APIs. A plugin waiting for a slow external system (payments, ERP, shipping) holds a worker for as long as that system takes to respond. A missing short timeout of its own in that plugin turns someone else’s outage into your 504.

#How does a 504 differ from 502 and 524?

• 502 Bad Gateway: the server behind the proxy answered, but the response was invalid. Often a crashed PHP-FPM process.
• 504 Gateway Timeout: no response in time. Most often overload or a slow request.
• 524: a Cloudflare code. The Cloudflare documentation states that it appears when the origin server does not respond within the default 125 seconds. Cloudflare advises asking the host to check for long-running processes and overload, and moving large operations to a channel that bypasses the proxy.

Behind a CDN you may therefore see two different codes for the same cause, depending on which link lost patience first.

#When should you raise the timeout, and when not?

Raising fastcgi_read_timeout or the PHP time limit is justified for a single, deliberately long operation, for example a manual import. For a site that shows 504 to visitors, it is masking: the slow request still occupies a worker, only for longer, and the pool fills up faster.

PHP-FPM has a separate safeguard, request_terminate_timeout. The documentation describes it as the limit after which the process handling the request is killed, and gives the default value 0, meaning disabled. Set sensibly, it protects the pool from a single hung script.

#How do you fix a 504 step by step?

1. Establish the scope: the whole site, one address or only wp-admin.
2. Read the server and PHP-FPM logs from the time of the failure.
3. Turn on debug.log and reproduce the error.
4. Deactivate plugins (with WP-CLI or by renaming the directory), then reactivate them one at a time and measure the response time.
5. If object-cache.php exists, disable it as a test.
6. Check autoloaded options and overdue WP-Cron tasks.
7. Only at the end consider enlarging the pool or the timeouts, together with the hosting administrator.

If the 504 appeared right after an update, also see the guide on recovering WordPress after a failed update.

#When is this a job for a specialist?

When the logs point to the PHP-FPM pool but the host gives no access to its configuration. When the 504 returns after every fix. When a shop loses orders during the outage. For an audit meant to separate the cost of hosting from the cost of code, WordPress performance optimization helps. When the site is down right now and the cause is unknown, the rescue is WordPress repair and technical support.