Nginx / FIELD GUIDE

Fix Nginx 504 Gateway Timeout by Tracing Upstream Latency

Diagnose an Nginx 504 Gateway Timeout with upstream logs and curl timings. Compare connection delays, slow response headers and read timeouts.

Concept illustration of reverse proxy request paths
Concept illustration · All in Term. Not a screenshot or a measurement.

A 504 tells you a gateway did not receive a timely response from the next service. Identify the layer that emitted it, then determine which part of the upstream exchange ran out of time. This walkthrough uses a read-only reproduction and example timings to distinguish connection problems, delayed response headers and slow dependencies. Keep the original route and timestamp for a comparable retest.

Find the layer that returned the timeout

A browser may receive a 504 from a CDN, load balancer or Nginx instance. Find the matching request in the relevant access logs before editing a timeout directive. Record host, path and timestamp and use a request identifier when available. If no match appears, check log routing, timezones and the layer immediately upstream. Measure one safe request from the affected client perspective and capture its status and total time.

A useful record distinguishes the time when the client sent its request from the time the gateway returned the status. If the access log is written when the request completes, looking at the same second in the application log can miss a long-running operation. Search a bounded window that covers the entire request. Prefer a shared request identifier when available. If you add timing fields to a log format, keep the changes appropriate to the environment and verify a sample entry before depending on it.

THE BIG PICTURE

Choose a check for the task

  1. 01

    Connection phase

    Check routing and listening address

  2. 02

    Before headers

    Check workers and dependencies

  3. 03

    During body

    Check streaming behavior and read gaps

Conceptual workflow · follow each check before moving to the next step.

Read which upstream phase stalled

Match the request with the Nginx error log and read the phase described there. A connection that stalls points toward routing, an address or a busy listener. A delay before response headers directs attention to application work, queues and dependencies. A timeout while reading a response body can mean that the upstream stopped sending data for too long. Keep the observed phase in your incident note so you do not conflate all timeouts with slow application code.

With multiple upstreams, compare requests routed to each backend. A single saturated worker can produce intermittent timeouts while requests to other workers look healthy. Preserve the target address and timing in the evidence you share. When a request is retried upstream, the record may include several attempts. Review the retry policy and which operation was requested before drawing conclusions from a total time. A single user-visible response can represent more than one backend exchange.

Compare the options and decide what to check
Option or symptomWhat to look forWhere to start
Connection phaseUpstream connection stallsCheck routing and listening address
Before headersConnection opens, response is delayedCheck workers and dependencies
During bodyUpstream stops sending dataCheck streaming behavior and read gaps
Concept illustration of reverse proxy request paths
VISUAL FIELD NOTE / ORIGINAL ILLUSTRATION

Reverse proxy request paths

Find the gateway that emitted the timeout and match its request record.

Workflow

Check routing and listening address

AI-generated concept illustration · not a screenshot, literal protocol diagram or measurement.

Reproduce from the proxy's network context

If the upstream speaks HTTP, test an approved endpoint from the place where the proxy runs. Match the scheme, hostname, route and host header needed for that test. A successful local test on your laptop is weaker evidence than a request made from the proxy's container or host namespace. Record connect time, time to first byte and total time. In curl, first-byte time is cumulative from the start of the request, so avoid treating it as an additional segment to add to connect time.

Try to reproduce the issue with a safe request that retains the expensive part of the original route. Replacing a report request with a health probe is useful for establishing a baseline, but the health route may never check the database query or external dependency that makes the report slow. If the real action changes data, reproduce it using a staging fixture or use an existing trace. Avoid replaying a live write simply to collect timing information.

Reverse proxy request paths
A CLOSER LOOK

Reverse proxy request paths

Find the gateway that emitted the timeout and match its request record.

Concept illustration, not an application screenshot.

Compare example timings across requests

The chart compares fictional total times for a public health check, a direct upstream health check and the affected upstream route. In this example the affected route takes far longer than either health check. Follow that route into application logs or traces and look for blocked workers, long database queries or slow external calls. Do not infer that all requests are healthy from one quick health endpoint. Reproduce under comparable traffic when that is part of the condition.

In this example, the affected upstream route takes 4,100 milliseconds and the upstream health check takes 52 milliseconds. The roughly 79-fold difference compares two different routes in the same example. It gives you a reason to inspect the report path and its dependencies before changing a shared proxy setting.

ILLUSTRATIVE DATA · NOT A BENCHMARK

Example response times by route and vantage point

Unit: milliseconds. Synthetic example values, not production measurements.

Public health
120
Upstream health
52
Affected upstream route
4,100

Bars start at zero and share the same linear scale. Exact values are printed alongside each bar.

Concept illustration of upstream response timing
VISUAL FIELD NOTE / ORIGINAL ILLUSTRATION

Upstream response timing

Distinguish connection time from the time until the first response byte.

Workflow

Check workers and dependencies

AI-generated concept illustration · not a screenshot, literal protocol diagram or measurement.

Review timeout settings after you have evidence

Nginx documents separate proxy connection and read timeout settings. Its upstream read timeout applies between successive read operations. An edge may have its own independent deadline. A longer timeout can be reasonable for a reviewed workload with suitable resource limits, but also lets work occupy capacity longer. Confirm which layer and phase need a change and document how you will reverse it. Validate the configuration before reloading and compare behavior under the same request shape.

A repair can live in application work, capacity management or proxy configuration. For example, an expensive report may need a query change validated with realistic data, while a rare network timeout needs an investigation of the path. Record the intended effect of your proposed change before applying it. Compare the same route with the same request shape afterward and keep the status, response time and evidence from the dependency together. A shorter duration is meaningful only if the request still returns the expected result.

Retest the route that users reported

Consider a report endpoint with a normally quick health check and a request that takes several seconds before the first byte arrives. Run the comparable staging request twice and check whether an upstream connection is established promptly both times. If it is, correlate the delay with the application request identifier. One trace might show a worker waiting for a database connection, while another shows time spent in a specific query. Those observations point to different remedies. When you try a fix, check the report body as well as the latency. A fast failure response could bring down the timing number while leaving the user unable to obtain the report. Preserve the previous baseline and include the conditions that made the symptom reproducible.

Confirm that the original route returns the expected content, record the time and inspect fresh errors. Check a nearby route to catch side effects from edits to a shared location. All in Term gives a Mac operator SSH, remote files and a way to inspect readable remote logs in the same workspace. Download it for a staging trial if you frequently move between those checks. Keep a short record that says which phase stalled and what observation confirmed recovery.

Concept illustration of application and database dependency
VISUAL FIELD NOTE / ORIGINAL ILLUSTRATION

Application and database dependency

Correlate a slow route with work in the application and downstream services.

Workflow

Check streaming behavior and read gaps

AI-generated concept illustration · not a screenshot, literal protocol diagram or measurement.

Inside the application: a scoped local example

This capture uses the shipped UI component in an isolated renderer. The host, files and service data are demonstrations, not a production session. It illustrates the surrounding workflow; it does not verify every service-specific command in this guide.

Nginx component displaying results parsed from 30 synthetic request records; no live Nginx server was inspected.
Actual application component · local demonstration · sample data
Nginx component displaying results parsed from 30 synthetic request records; no live Nginx server was inspected. Captured 2026-11-08. Open the image to inspect details.

Parse a known access-log fixture

Executed the current Nginx log parser against 30 synthetic access records and one synthetic error record. These counts describe only that fixture.

Executed check

parseRawNginxLogs(accessFixture, "access", examplePath)

Recorded output

Parsed access records: 30
200 responses: 24
404 responses: 3
502 responses: 3
Parsed error records: 1

Recorded 2026-11-08. Executed locally against synthetic fixtures. No production host or database was contacted. Read the recorded checks.

Explore the related All in Term workflow →

A small command example

Read the comments, confirm the active host and adapt any example names to your environment before running commands.

curl -sS -o /dev/null --connect-timeout 3 --max-time 10 -w 'status=%{http_code} connect=%{time_connect} first_byte=%{time_starttransfer} total=%{time_total}\n' https://shop.example.com/report

Further reading

Official documentation for the underlying tools. The workflows and synthetic examples above are editorial guidance, not performance claims.

Follow Nginx logs in All in Term

Keep the remote terminal and a readable Nginx log available while you reproduce the timeout.

Download & setup ↗