Nginx fastcgi_cache_use_stale: Configuring Stale FastCGI Cache Fallback and Background Updates

Configuring fastcgi_cache_use_stale in Nginx

The fastcgi_cache_use_stale directive determines in which cases a stale cached response can be used when an error occurs during communication with a FastCGI server. By default, fastcgi_cache_use_stale is set to off. It can be configured in the http, server, or location contexts.

In the supplied documentation excerpts, caching is activated using fastcgi_cache with a shared memory zone defined by fastcgi_cache_path:

fastcgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;

server {
    location / {
        fastcgi_pass backend;
        fastcgi_cache cache_zone;
        fastcgi_cache_key $uri;
        fastcgi_cache_use_stale error timeout invalid_header updating http_500 http_503;
    }
}

Failure Conditions and Parameter Mechanics

The parameters of fastcgi_cache_use_stale match the parameters of the fastcgi_next_upstream directive:

• error: Permits using a stale cached response when an error occurs while establishing a connection with the server, passing a request to it, or reading the response header. It also permits using a stale cached response if a FastCGI server to process a request cannot be selected.
• timeout: Permits using a stale cached response when a timeout occurs while establishing a connection with the server, passing a request to it, or reading the response header. The fastcgi_connect_timeout directive defines a timeout for establishing a connection (default 60 seconds, which usually cannot exceed 75 seconds).
• invalid_header: Permits using a stale cached response when a server returns an empty or invalid response. Under fastcgi_buffer_size (defaulting to 4k or 8k depending on platform for reading the first part of the response containing a header), if the header exceeds the buffer size, the response is considered invalid.
• updating: Permits using a stale cached response if the cache entry is currently being updated. This minimizes accesses to FastCGI servers when updating cached data.
• http_500, http_503, http_403, http_404, http_429: Permits using a stale cached response when the server returns the corresponding HTTP status code.
• off: Disables using a stale cached response.

Background Updates with fastcgi_cache_background_update

The fastcgi_cache_background_update directive (introduced in Nginx 1.11.10; default off) allows starting a background subrequest to update an expired cache item while a stale cached response is returned to the client. The documentation explicitly notes that it is necessary to allow the usage of a stale cached response when it is being updated, by including the updating parameter:

location / {
    fastcgi_pass backend;
    fastcgi_cache cache_zone;
    fastcgi_cache_key $uri;
    fastcgi_cache_use_stale error timeout updating;
    fastcgi_cache_background_update on;
}

Handling Application Errors with fastcgi_catch_stderr

The fastcgi_catch_stderr directive sets a string to search for in the error stream of a response received from a FastCGI server. If the string is found, Nginx considers that the FastCGI server has returned an invalid response. In the official documentation example, this is demonstrated with passing requests to the next upstream server:

location /php/ {
    fastcgi_pass backend:9000;
    fastcgi_catch_stderr "PHP Fatal error";
    fastcgi_next_upstream error timeout invalid_header;
}

The documentation establishes that finding the configured string causes Nginx to treat the response as an invalid response. While fastcgi_cache_use_stale supports the invalid_header parameter (matching fastcgi_next_upstream for empty or invalid responses), the visible excerpts do not include a combined configuration example demonstrating fastcgi_catch_stderr directly driving stale cache fallback.

Research Method and Limitations

This article was prepared strictly from the supplied public documentation excerpts for ngx_http_fastcgi_module. Material limitations include reliance on truncated documentation excerpts and the absence of accessible competing coverage. Because excerpts were truncated, surrounding operational details—such as whether a stale cache fallback interacts directly with fastcgi_catch_stderr in production or how full upstream retry sequences resolve when cache entries are absent—remain unverified beyond the exact documented directives.

Source references

• nginx.org documentation
• nginx.org documentation