Fix Nginx 504 Gateway Timeout

The Problem

Visitors see '504 Gateway Timeout' on pages that take too long to respond — Nginx gave up waiting for the backend application to finish, usually because the request is genuinely slow or the backend is stuck.

About this problem

A 504 is specifically a timeout, different from a 502 (which means the backend failed or refused outright) — it means Nginx successfully connected to the upstream but gave up waiting for a complete response within its configured timeout window. It's common with long-running reports, large file uploads/exports, slow third-party API calls the backend depends on, or a database query that's become slow as data has grown.

It often only shows up under specific conditions (a particular heavy report, a big import) rather than across the whole site, which is a useful diagnostic clue in itself.

What's Included

• Identifying exactly which request(s) are timing out and why they take as long as they do
• Checking whether the backend is genuinely slow or actually stuck/hung
• Adjusting Nginx's proxy timeout settings where a longer wait is the correct fix
• Optimising or offloading the slow operation itself where that's the real underlying cause

What's NOT Included

• Rewriting slow application code or database queries beyond identifying them (can be scoped as a follow-up)
• Permanently raising timeouts to mask a problem that should actually be fixed at the source
• Scaling server resources — a capacity decision for you

How It Works

1. Reproduce the timeout and check Nginx's error log for the specific upstream timeout message and the request involved.
2. Check the backend's own logs and resource usage during that request to see if it's genuinely slow or actually hung.
3. If genuinely slow but legitimate (a big report, large export), raise the relevant proxy_read_timeout/proxy_connect_timeout values appropriately.
4. If stuck rather than slow, investigate the specific cause (a hanging external API call, a lock in the database) rather than just extending the timeout.
5. Re-test the specific request that was failing to confirm it now completes successfully.

In practice: you buy the service, send over whatever access or details the job needs, I investigate and do the work, and you confirm it's resolved before we call it done.

Frequently Asked Questions

What does a 504 Gateway Timeout mean?

It means Nginx (or another proxy) successfully reached the backend application but gave up waiting for a complete response within its configured time limit.

Is a 504 the same as a 502 error?

No. A 502 means the backend gave an invalid or no response at all; a 504 means it was taking too long to respond and the proxy timed out waiting.

Can I just increase the timeout to fix a 504 error?

Sometimes, if the request is legitimately slow and expected to take a while — but if the backend is actually stuck or hung, raising the timeout just delays the same failure rather than fixing it.

Why does my 504 error only happen on one specific page?

That page likely triggers something unusually slow — a large report, a bulk operation, or a call to a slow third-party service — while the rest of the site responds quickly enough to stay under the timeout.

Can a slow database query cause a 504 error?

Yes, if a query takes longer than the configured proxy timeout to return, Nginx gives up waiting on the connection even though the database might eventually have answered.

What's a sensible timeout value for Nginx?

It depends entirely on what the backend legitimately needs — commonly a handful of seconds for typical requests, with specific longer values set only for routes known to take longer, like file exports.