Short answer: a 504 Gateway Timeout means an upstream server (PHP, or a proxy in front of it) did not respond within the allowed time and the request was cut off. Something took too long — a slow query, a hung external call, or a heavy operation on a web request.
What typically times out
- An import, export or backup running through the browser instead of the command line.
- A slow or unresponsive external API called during page generation.
- A database query scanning far more rows than it should, often on a large table.
- Bulk operations — regenerating thumbnails, updating many products.
- A CDN or proxy timeout set shorter than the origin needs.
Find the slow operation
Enable WP_DEBUG_LOG and check the server and PHP-FPM logs for what was running when the timeout hit. Use Query Monitor on the slow page to expose an unindexed or unbounded query and the plugin that fires it. If one specific action triggers it — an import, a report — that narrows the search immediately.
Raise the timeout only where appropriate
For a genuine one-off migration you can raise the proxy and PHP timeouts temporarily. But on a page real visitors load, a higher timeout just holds a worker open longer and reduces how many visitors you can serve. The durable fix is to make the operation fast, or move genuinely long jobs to WP-CLI or a scheduled process.
Verify
Reproduce the exact action that timed out under realistic conditions, and confirm it now completes well inside the limit rather than just under it. If it was an external API, confirm the site degrades gracefully instead of hanging when that service is slow.
WP REPAIR INCIDENT STANDARD
Reconstruct the incident before fixing it
A 504 is the gateway giving up while an upstream request remains unfinished. The repair is to find the slow operation or dependency, not simply extend every timeout.
- 1
Record the exact route or action and gateway timeout duration.
- 2
Correlate proxy, PHP-FPM, application and slow-query logs.
- 3
Identify imports, reports, external APIs or unbounded queries tied to the request.
- 4
Move long batch work off the web request or add bounded, observable timeouts to dependencies.
What must be verified
- The original operation completes with a safe margin.
- Normal requests remain responsive while it runs.
- External dependencies time out and degrade predictably.
Official technical sources
This guide explains the diagnosis. If the site is affected now, the intervention should preserve a rollback path and verify the real business journey.
See the emergency repair service →