Introduction

A 504 Gateway Timeout means the proxy, CDN, or load balancer waited for the upstream service and did not receive a complete response in time. The gateway is available, but the service behind it is too slow, blocked, or stalled to finish the request.

Symptoms

  • Visitors see 504 Gateway Timeout
  • The error appears only on dynamic routes or heavy admin actions
  • Direct requests to the app may be slow even when they do eventually work
  • The issue started after a deploy, traffic spike, or dependency slowdown
  • Logs show upstream timeout, read timeout, or gateway timeout messages

Common Causes

  • The upstream app is overloaded or blocked on slow queries
  • Database, cache, or third-party API dependencies stall the request path
  • Proxy timeout settings are shorter than the real application response time
  • Background jobs or resource starvation reduce available workers
  • A network path between proxy and upstream is dropping or stalling connections

Step-by-Step Fix

  1. Identify where the timeout occurs by comparing proxy logs, application logs, and dependency metrics for the same request window.
  2. Measure the slow upstream route directly and determine whether the delay comes from application code, database queries, or external services.
  3. Check worker saturation, CPU, memory, and connection pools to see whether the app can process requests under current load.
  4. Review timeout settings across the full chain so one layer is not cutting off a request earlier than expected.
  5. If the route became slow after a deploy, inspect the code path, queries, and external calls added in the change.
  6. Reduce the slow work by optimizing queries, caching repeated reads, or moving heavy processing out of the request path.
  7. Increase timeout values only when the request is valid and the upstream can complete reliably within a reasonable window.
  8. Re-test the exact failing route through the public gateway and confirm it now returns a normal response before the timeout threshold.
  9. Keep latency and timeout monitoring on key upstream paths so performance regressions are caught before they become outages.