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 →ABOUT THIS SYMPTOM
Frequently asked questions about this guide.
Is a 504 the same problem as a 503 error?+
No. A 504 means an upstream server, typically PHP or a proxy in front of it, didn't respond within the allowed time, pointing at something taking too long to execute. A 503 usually means the server couldn't handle the request at all, often due to a stuck maintenance file or exhausted resources, not a slow operation.
Should I just raise the timeout limit whenever I see a 504?+
Only for a genuine one-off task like a migration. Raising the timeout on a page real visitors load just keeps a worker occupied longer and reduces how many visitors the server can handle at once, it doesn't fix the underlying slow operation.
What's the right way to run a large import or export without hitting a 504?+
Run it through WP-CLI or a scheduled background process instead of through the browser. Browser-triggered imports, exports, and backups are exactly the kind of long-running operations that commonly exceed the proxy or PHP timeout.
How do I find out which query or plugin is actually causing the timeout?+
Enable WP_DEBUG_LOG and check the server and PHP-FPM logs for what was executing when the timeout occurred, then use a tool like Query Monitor on the slow page to expose an unindexed or unbounded query and identify the plugin firing it.