504 Gateway Timeout during long-polling upstream responses

Direct Resolution

To prevent 504 Gateway Timeouts during long-polling, you must ensure that the proxy_read_timeout is set to a value higher than the maximum duration the upstream server holds a request before sending a response or a heartbeat. If the upstream server is silent for 60 seconds but proxy_read_timeout is 30s, Nginx will terminate the connection.

# Example configuration for a 5-minute long-poll window
location /poll {
    proxy_pass http://upstream_backend;
    proxy_read_timeout 300s;
    proxy_connect_timeout 75s;
    proxy_send_timeout 75s;
}

Analysis of Timeout Mechanisms

Hard vs. Incremental Timeouts

Nginx does not provide a native "hard request timeout" that operates independently of the read timeout for proxying. The proxy_read_timeout is an inter-packet timer; it resets every time the proxy receives a chunk of data from the upstream server. There is no built-in directive to say "allow this request to last 10 minutes total, regardless of data flow, but timeout if no data is seen for 30 seconds." To implement a hard limit, you must manage the request lifecycle within the upstream application logic itself.

Interaction with Keep-Alive

There is a critical distinction between TCP keep-alives and the HTTP read timeout:

• TCP Keep-Alives: These operate at the transport layer to ensure the connection is still physically open. They prevent intermediate firewalls from dropping "idle" connections but do not reset the Nginx proxy_read_timeout timer.
• Application Heartbeats: For long-polling, the upstream server should send periodic "heartbeat" bytes (e.g., a newline or a comment) to the proxy. Because proxy_read_timeout resets upon receiving data, these heartbeats keep the connection alive without requiring an excessively high timeout value.

Verification Steps

1. Check Error Logs: Confirm the 504 is originating from Nginx by searching for upstream timed out (read) in the error.log.
2. Timing Analysis: Use curl -v to measure the exact elapsed time between the request and the 504 response. If the time matches your proxy_read_timeout exactly, the proxy is the bottleneck.
3. Upstream Audit: Verify the upstream server's internal timeout settings to ensure it isn't closing the connection before Nginx does.

Missing Diagnostic: Are there additional load balancers (e.g., AWS ALB, Cloudflare) in front of Nginx? If so, their independent timeout settings may trigger a 504 before the request even reaches the Nginx proxy_read_timeout threshold.