NGINX proxy_next_upstream: Documented Failover Conditions and Retry Boundaries

When using NGINX as an HTTP reverse proxy, the ngx_http_proxy_module defines how and when requests pass to another upstream server. This failover behavior is governed primarily by the proxy_next_upstream directive alongside limits on time and tries.

The Client-Transmission Boundary

Passing a request to the next server is only possible if nothing has been sent to the client yet. If an error or timeout occurs in the middle of transferring a response, fixing this is impossible.

Response buffering settings influence when client transmission occurs. Under proxy_buffering on (the default), NGINX reads the upstream response into memory buffers (configured by proxy_buffer_size and proxy_buffers) or temporary files. When proxy_buffering off is set, NGINX passes the response synchronously to the client as it is received. However, the documentation establishes that regardless of buffering, failover cannot occur once response data transmission to the client has begun.

Documented Failover Conditions and Error Cases

The proxy_next_upstream directive specifies the cases in which a request should be passed to the next server. Its default setting is error timeout, and it is valid in the http, server, and location contexts.

The directive outlines several categories of communication outcomes:

• Automatic Unsuccessful Attempts: The cases of error, timeout, invalid_header, and denied are always considered unsuccessful attempts, even if not specified in the directive. The denied parameter (where the server denies the connection) appeared in version 1.29.3 and is available only as part of a commercial subscription.
• Explicitly Configurable Status Codes: The cases of http_500, http_502, http_503, http_504, and http_429 (the latter added in version 1.11.13) are considered unsuccessful attempts only if specified in the directive.
• Excluded Status Codes: The cases of http_403 and http_404 are never considered unsuccessful attempts.
• Non-Idempotent Methods: Normally, requests with a non-idempotent method (POST, LOCK, PATCH) are not passed to the next server if a request has already been sent to an upstream server (introduced in version 1.9.13). Specifying the non_idempotent parameter explicitly allows retrying such requests.
• Disabling Failover: Specifying off disables passing a request to the next server entirely.

Limiting Retries and Time

The visible documentation states that passing a request to the next server can be limited by the number of tries and by time.

For time limits, the module provides the proxy_next_upstream_timeout directive:

• Syntax: proxy_next_upstream_timeout time;
• Default: proxy_next_upstream_timeout 0;
• Context: http, server, location
• Version: Appeared in version 1.7.5.

A value of 0 disables the time limitation.

Research Method and Limitations

This technical explainer was prepared strictly from the supplied public documentation excerpts for NGINX’s ngx_http_proxy_module. Competing coverage was not available in the provided evidence. Due to excerpt truncation in the provided source text, the dedicated reference block detailing the exact syntax and defaults for proxy_next_upstream_tries was not visible; only the conceptual statement that retries can be limited by try count was verified. No hands-on tests or performance benchmarks were conducted.

Source references

• nginx.org documentation
• nginx.org documentation
• nginx.org documentation