Nginx proxy_cache_use_stale: Serving Stale Cached Content During Upstream Failures and Updates

Overview

When an upstream server encounters communication errors, timeouts, or specific HTTP status codes, Nginx can be configured to serve an expired (stale) cached response using the proxy_cache_use_stale directive from the ngx_http_proxy_module.

Syntax and Context

The proxy_cache_use_stale directive defines the conditions under which a stale cached response can be sent during communication with the proxied server.

• Syntax: proxy_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | off ...;
• Default: proxy_cache_use_stale off;
• Context: http, server, location

The directive parameters match the parameters of the proxy_next_upstream directive.

Documented Parameters and Upstream Conditions

The supplied documentation defines the following conditions:

• error: Considered an unsuccessful attempt of communication with a server.
• timeout: Considered an unsuccessful attempt of communication with a server.
• invalid_header: A server returned an empty or invalid response; considered an unsuccessful attempt.
• http_500: A server returned a response with code 500 (considered an unsuccessful attempt only if specified).
• http_502: A server returned a response with code 502 (considered an unsuccessful attempt only if specified).
• http_503: A server returned a response with code 503 (considered an unsuccessful attempt only if specified).
• http_504: A server returned a response with code 504 (considered an unsuccessful attempt only if specified).
• http_403: A server returned a response with code 403 (never considered an unsuccessful attempt).
• http_404: A server returned a response with code 404 (never considered an unsuccessful attempt).
• http_429: A server returned a response with code 429 (appeared in version 1.11.13; considered an unsuccessful attempt only if specified).
• updating: Permits returning a stale cached response while the cache item is being updated.
• off: Disables the use of a stale cached response.

Background Updates with proxy_cache_background_update

Nginx 1.11.10 added the proxy_cache_background_update directive:

• Syntax: proxy_cache_background_update on | off;
• Default: proxy_cache_background_update off;
• Context: http, server, location

This directive allows starting a background subrequest to update an expired cache item while returning a stale cached response to the client. To use this functionality, the configuration must allow the usage of a stale cached response when it is being updated (such as including updating in proxy_cache_use_stale), and an existing stale cached response must be present.

Documented Operational Constraints

• Client Transfer Boundary: Passing a request or falling back is only possible if nothing has been sent to a client yet. If an error or timeout occurs in the middle of transferring a response, fixing this is impossible.
• Buffer Limits: If the response header exceeds proxy_buffer_size (default 4k or 8k depending on platform), the response is considered invalid.
• Inactive Cache Expiry: Cached data not accessed during the time specified by inactive (default 10 minutes in proxy_cache_path) get removed from the cache regardless of freshness. A stale entry must still reside in cache to be served.

Supported Configuration Snippet

The following example illustrates applying these directives within a cache zone:

http {
    proxy_cache_path /data/nginx/cache keys_zone=cache_zone:10m;

    server {
        location / {
            proxy_pass http://backend;
            proxy_cache cache_zone;

            proxy_cache_use_stale error timeout invalid_header updating http_500 http_502 http_503 http_504;
            proxy_cache_background_update on;
        }
    }
}

Note: http://backend represents an upstream address or server group that must be defined elsewhere in your configuration. A stale response will only be returned if an unpurged, non-evicted cached entry already exists for the request.

Research Method and Limitations

This technical summary was prepared exclusively from visible public excerpts of the official Nginx ngx_http_proxy_module documentation retrieved on September 17, 2026. Material limits include truncated documentation excerpts that omit full downstream error handling details when stale caching is disabled, as well as the absence of FastCGI directives and non-functional competitor tutorial pages.

Source references

• nginx.org documentation
• nginx.org documentation