What Does a 504 Gateway Timeout Mean? And Whose Fault It Is

A 504 Gateway Timeout means a server in the middle asked another server for something and gave up waiting. The page you wanted exists. The machine that would have built it did not answer in time, and the machine in front of it stopped holding the door open.

If you are a visitor: it is not your computer, not your browser, and not your connection. Every error code beginning with 5 is the site’s side reporting its own problem. Clearing your cache will not help, and neither will trying a different browser.

The two-server picture

Almost no website is one machine. A request typically arrives at something in front - a load balancer, a reverse proxy, a CDN edge - and that thing passes it back to whatever actually runs the application, then relays the answer to you.

A 504 is the front machine’s report on the back one: I asked, I waited, nothing came, here is a status code so you are not left staring at a blank tab. The site’s application never got the chance to tell you anything, which is why a 504 page usually looks generic rather than like the site around it.

That also explains the timing. A 504 typically arrives after a long pause - ten seconds, thirty, sixty - because the pause is the point. Something was still trying.

504 against 502, which are constantly confused

They come from the same place and mean different things, and knowing which one you have narrows the cause considerably.

502 Bad Gateway

The upstream server answered, and the answer was unusable - a connection refused, a crashed process, garbage on the wire. Usually fast

504 Gateway Timeout

The upstream server did not answer at all within the time allowed. Usually slow, and the delay before the error is itself a clue

Roughly: 502 is “it said something wrong”, 504 is “it said nothing yet”. A 502 points at something being broken or down; a 504 points at something being slow, stuck, or overloaded.

One wrinkle worth knowing, because most articles miss it: some providers use their own codes for this. Cloudflare returns 524 when your origin accepts a connection and then takes too long to respond, which is the same story told by a different layer. If you are behind a CDN, the number you get may be theirs rather than the standard one.

If you are the visitor

There is very little to do, and that is the honest answer rather than a short one.

Wait a minute and reload. A 504 is often transient - one slow query, one restarting process, one burst of traffic. If it persists, check whether the service has a status page or whether anyone else is reporting it, because the failure is on their side and only they can fix it.

The one genuinely useful thing you can do is tell them, with enough detail that they can find it. Which page, what time, and what you were doing. A 504 on a checkout at 14:32 is something an engineer can go and look up in a log; “your site is down” is not.

If it is your site

Four causes account for most of them, in roughly this order.

• One slow thing. A database query without an index, an external API you call while the user waits, a report that grew past the size it was designed for. The request is not stuck, it is just slower than the proxy’s patience.
• A timeout set below reality. Nginx defaults to sixty seconds for a proxied read. If your slowest legitimate request takes ninety, you will serve 504s to the people using the feature that matters most.
• Exhausted workers. Every application process is busy, so new requests queue behind them and never reach the code at all. This one arrives in bursts and looks like the site failing entirely, because in effect it is.
• The network path. A security group, a DNS change, a service that moved. Less common, and usually total rather than intermittent.

Find out which layer emitted it before changing anything. The proxy’s own access log records the status it returned and how long it waited; the application log will either show a request that took that long or show nothing at all for that moment. Those two cases have opposite fixes, and guessing between them is how people end up raising a timeout that was never the problem.

Raising the timeout is the tempting move and is usually wrong on its own. It converts a fast failure into a slow one and moves the queue somewhere else. It is the right move only when you know the work legitimately takes that long and cannot be made asynchronous.

The reason these are so hard to chase later

A 504 is a moment. By the time somebody mentions it, the slow query has finished, the workers have drained, the burst has passed, and the page loads perfectly when you try it.

So the report arrives as “it was broken earlier” and there is nothing to look at. What would make it findable is what the browser saw at the time: which request timed out, against which host, how long it waited, and what else on the page had already failed. That is in the network panel while it is happening and gone the moment the tab is closed.

That is the case for capturing it at the moment rather than describing it afterwards - a HAR file is the standard way to do that by hand, and it is exactly what the network log in a bug report carries. The same evidence answers the other question worth asking early, which is whether the timeout was your service or somebody else’s: the host column says which.

In one paragraph

A 504 means the server in front asked the server behind and ran out of patience. It is the site’s problem rather than yours, it usually means slow rather than broken, and it is distinguished from a 502 by the pause before it. If it is your site, find out which layer timed out before touching any timeout setting, because the log that recorded nothing and the log that recorded ninety seconds are telling you two different stories.