504 Gateway Timeout

Every proxy has a patience limit. It forwards your request to the application behind it, starts a timer, and waits for a response. If the timer runs out first, it abandons the request and returns 504 Gateway Timeout.

The important thing about this error is what it rules out. The DNS resolved. The connection succeeded. The proxy was able to hand the request over. Something at the other end accepted it. The only thing that did not happen is a reply.

The application is alive and stuck

This is the distinction from a 502, and it changes what is wrong.

A 502 means the proxy could not get a valid response - Usually because nothing was there. That points at a dead process, and dead processes get restarted automatically.

A 504 means the process is there, took your request, and is sitting on it. Nothing will restart it, because from the supervisor's point of view it is running perfectly. It is just not finishing.

What makes a request hang

• A slow database query. The single most common cause. A query without an index, a report over a large table, or a lock held by another transaction. Under load this compounds: Slow queries hold connections, the pool fills, and requests that would be fast start queueing behind them.
• A blocked call to something else. The application is waiting on a third-party API, a payment gateway, an email service or an internal microservice that is itself hung. If that call has no timeout of its own, the application will wait forever and the proxy will time out first.
• Genuinely heavy work. Generating a large export, processing an upload, rendering a PDF. Anything that legitimately takes longer than the proxy's limit will always 504, no matter how healthy the system is.
• Thread or worker exhaustion. Every worker is busy with long requests, so new requests wait in a queue and time out before being picked up. This produces 504s for fast endpoints that are not themselves slow, which is confusing until you see it.
• A deadlock. Two operations waiting on each other. The request will never complete regardless of how long anyone waits.

Reading the wait

How long the page took to appear is real information, because it tells you whose timeout expired.

If you consistently wait the same length of time before the error appears, that number identifies the component that gave up - And therefore where in the chain to look.

Why raising the timeout is the wrong fix

It is the first thing everyone reaches for and it usually makes things worse. A longer timeout means slow requests occupy workers for longer, which means fewer workers are available, which means more requests queue, which means more of them time out. You have converted a fast failure into a slow collapse.

The correct responses are to make the work faster, or to make it asynchronous. Anything that legitimately takes more than a few seconds - An export, a video encode, a bulk import - Should return immediately with a job identifier and let the client poll. That way nothing is ever waiting on a socket for a minute.

What to do as a visitor

Waiting is more likely to work here than with most errors, because 504s are frequently load-related and load passes. Come back in a few minutes rather than reloading immediately - A reload adds another slow request to a system that is already short of capacity.

If the 504 happens only on one specific action - Submitting a large form, running a search with a wide date range, exporting a report - That is a strong signal it is a slow operation rather than a site-wide problem, and worth reporting with those specifics.

If it is your site

Find what is slow before touching any configuration. Enable the slow query log; it usually names the problem in one line. Check whether an external dependency has become slow, and whether your calls to it have timeouts set - An outbound call with no timeout is the most common way one third party's incident becomes your outage.

Then check worker saturation. If every worker is busy, the fix is not more workers, it is finding what they are all waiting on. Adding workers to a system bottlenecked on a database just moves the queue somewhere less visible.