{
  "id": 21295604,
  "title": "Nginx 504 Is a Read Timeout — Debug It Along the Request Path, Not in a Random Order",
  "url": "https://urgent.news/2026/11/22/nginx-504-is-a-read-timeout-debug-it-along-the-request-path-not-in-a",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-11-22T21:59:14.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/jun_liu_ca219b73a8f1489b5/nginx-504-is-a-read-timeout-debug-it-along-the-request-path-not-in-a-random-order-5f1i"
  },
  "original_language": "en",
  "account": "When a 504 error occurs at 3 AM, the natural reaction is to examine the backend logs, restart the service, and increase the timeout. However, this loop often closes the ticket without resolving the issue. A more effective mental model is that a 504 indicates only one thing: the upstream never sent any data before the proxy_read_timeout expired. This single fact breaks down the diagnosis into six root causes that occur sequentially along the request path, and debugging them in that order eliminates guesswork.\n\nA 504 is not an indication of a problem with Nginx itself; it serves as a messenger. The worker sends the request to the upstream and then enters a read loop. The worker checks if the proxy_read_timeout has been exceeded during each event-loop cycle. If the timeout is exceeded, the upstream connection is closed, and Nginx returns a 504, logging: \"upstream timed out (110: Connection timed out) while reading response header from upstream.\" It is essential to differentiate between a read timeout (504) and a connect timeout (502), as they have different error codes in Nginx's source code.\n\nThere are six root causes of a 504 error, occurring in order along the request path:\n1. DNS resolution slowdown\n2. TCP connect\n3. SSL handshake\n4. Connection-pool acquisition\n5. Backend CPU saturation or event loop blockage\n6. Slow query or slow I/O (DB, ES, disk)\n\nThe most common cause is a misconfigured timeout (40%), followed by backend CPU issues (25%) and slow queries (20%). Connection pool exhaustion and SSL handshakes account for 8% and 5% of cases, respectively, while DNS issues make up 2%.\n\nThe access-log upstream_response_time field is the fastest way to distinguish between these cases: a 502 error has an upstream_response_time under a second, while a 504 error has an upstream_response_time equal to the proxy_read_timeout. If all 504 entries in your access log show the same upstream_response_time value, the issue is likely due to a timeout configuration rather than a dead backend.\n\nA common mistake is to increase the proxy_read_timeout to an excessively long value (e.g., 300 seconds) to \"fix\" the 504 error. This does not resolve the underlying problem but merely stretches the duration of the issue. Instead, set the timeout based on the real P99 response time (approximately 2-3 times the actual value), monitor the P99 curve after the change, and remember that increasing a timeout is a painkiller, not a cure.\n\nOne notable mistake is increasing the proxy_read_timeout from 60 seconds to 300 seconds, causing the 504 error rate to disappear. However, after a week, the P99 response time increased from 3 seconds to 45 seconds due to an unaddressed slow query. A related issue arises when using proxy_next_upstream_tries 2 with a proxy_read_timeout of 20 seconds; users may experience up to 40 seconds of perceived latency, leading to 499 errors instead of the desired 504 diagnosis. Ensure that the sum of all Nginx timeouts remains below the client timeout to avoid this problem.",
  "summary": "When a 504 alarm fires at 3 AM, the instinct is to grep the backend logs, restart the service, and bump the timeout. I've watched this loop close the ticket without fixing anything. The cleaner mental model is that a 504 tells you almost nothing about the backend by itself — it only tells you one thing: the upstream never returned a single byte before proxy_read_timeout expired. That single fact…",
  "key_points": [
    "504 error indicates upstream never sent data before proxyreadtimeout expired",
    "Six root causes of 504 error occur sequentially along request path",
    "Most common cause is misconfigured timeout at 40% of cases"
  ],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}