504 Gateway Timeout — And Why Raising the Timeout Is the Wrong Fix

How 504 Differs from 502

These two arrive from the same place — the front server — and are easy to confuse. The difference is whether the backend answered at all.

What Actually Causes 504s

• A slow database query. Almost always the top cause. A missing index on a table that has grown means a query that took 50 ms last year now takes 40 seconds.
• A slow or unresponsive external API. Your code calls a payment gateway, a shipping quote or a mail service that stops responding, and your page waits for it with no timeout of its own.
• A heavy scheduled job running in the request. Imports, exports, report generation and bulk emails that were fine with a hundred rows and are not fine with a hundred thousand.
• Not enough PHP-FPM workers for the traffic. Requests queue behind each other until the ones at the back exceed the timeout, even though each individual request is reasonably fast.
• An inefficient plugin or a bad loop. A query inside a loop that runs once per row turns a single page load into thousands of round trips.
• A server that is out of resources. When CPU is saturated or the machine is swapping, everything slows down at once and normal requests start exceeding the deadline.

Why Raising the Timeout Does Not Fix It

Increasing the timeout from 60 to 300 seconds does make the error go away, and that is exactly the problem — it hides a symptom that was telling you something true. The visitor now stares at a blank tab for five minutes instead of getting an error in one. Almost nobody waits.

Worse, it makes the underlying failure spread. Every request that is now allowed to run for five minutes holds a worker process for five minutes. With a fixed number of workers, a handful of slow requests can consume all of them, and requests that would have been perfectly fast start queueing behind them. Raising the timeout converts a problem affecting one page into a problem affecting the whole site.

There is one legitimate case: a genuinely long-running operation that a human deliberately triggered and is waiting for, such as a large import in an admin panel. Even then, the right answer is usually to move the work to a background job and show progress, rather than holding an HTTP connection open.

Fixing the Actual Cause

• Find out what is slow before changing anything. Enable the MySQL slow query log, or use a profiler such as Query Monitor on WordPress. Guessing wastes far more time than measuring.
• Add the missing index. When a slow query is the cause, an index on the column being filtered or joined is frequently the entire fix, and can turn 40 seconds into milliseconds.
• Put a timeout on every outbound call your code makes. If an external API is unresponsive, your page should give up after a few seconds and degrade gracefully rather than waiting as long as the gateway allows.
• Move long jobs out of the request. Imports, exports and report generation belong in a queue or a cron task, with the page returning immediately and reporting progress separately.
• Cache the expensive parts. A page rebuilt from scratch on every request will eventually exceed any deadline; a cached one will not.
• Increase the number of PHP-FPM workers if requests are queueing rather than individually slow. This is a real fix when the problem is concurrency, and useless when the problem is one slow query.
• Give the server more resources if it is genuinely saturated. If CPU sits at 100% during normal traffic, no amount of tuning will help — the machine is too small for the workload.