Home Server & Self-Hosting

Serving Stale Content with NGINX - Trade a Little Freshness for a Smaller Outage

Serving Stale Content with NGINX - Trade a Little Freshness for a Smaller Outage

An application server stops responding, but NGINX still has yesterday's public article in its cache. Which response is more honest: the older article or a fresh 502 Bad Gateway page?

There is no universal answer. An old documentation page may remain useful during a short outage. An old account balance, access decision, or emergency correction may be unacceptable. Serving stale content is therefore not simply a performance switch. It is a policy that trades some freshness for limited continuity, and the trade only makes sense when the response, cache key, and failure window are understood.

NGINX can make that policy explicit with proxy_cache_use_stale. The useful part is not the directive by itself, but the boundaries around it: what may enter the cache, which failures qualify, how long old content remains tolerable, and how an operator can tell when fallback is happening.

Stale does not mean missing or corrupt

RFC 9111 calls a stored response fresh while its age has not exceeded its freshness lifetime. After that point it is stale. Stale says something about age, not integrity. The cache may still hold a complete response that was valid when it was stored.

Under ordinary conditions, a cache can revalidate that response with the origin, often by sending If-None-Match or If-Modified-Since. The origin can confirm it with 304 Not Modified or return a new representation. During an origin failure, that conversation cannot necessarily finish. A stale-on-error policy permits the cache to use the older stored response instead of forwarding the failure.

That fallback has two prerequisites that are easy to miss:

  • A matching cache entry must already exist. A cold request cannot fall back to an object that was never stored.
  • The entry must still be retained. In NGINX, the inactive parameter can remove an entry after a period without access, regardless of whether its freshness and permitted stale windows tell a different story.

Stale delivery is therefore a conditional safety net, not an offline copy of the whole site and not an availability guarantee.

Three clocks answer different questions

A careful configuration separates three kinds of time:

  1. Freshness lifetime: how long the response may normally be reused without validation, commonly controlled by max-age, s-maxage, Expires, or an NGINX cache-validity rule.
  2. Permitted staleness: how long an expired response remains acceptable under a specific exception, such as an origin error.
  3. Cache retention: how long NGINX keeps an entry that is not being accessed, controlled in part by inactive, cache size, and eviction.

These are not interchangeable. A response can be stale but still retained, fresh but evicted for space, or retained far beyond the period in which policy allows it to be served. Calling all three values “the cache timeout” hides decisions that should remain separate.

NGINX policy and HTTP response policy

There are two useful places to express permission to serve stale content.

At the reverse proxy, NGINX documents proxy_cache_use_stale with specific conditions such as error, timeout, invalid_header, updating, and selected HTTP status codes. It is off by default. This gives the infrastructure operator a policy for a configuration scope.

proxy_cache_use_stale error timeout invalid_header
                      http_500 http_502 http_503 http_504;

At the origin response, the extensions defined by RFC 5861 can attach a bounded policy to the representation itself:

Cache-Control: public, max-age=300, stale-if-error=900

This example says that the response is fresh for 300 seconds and may be used when an error occurs for up to another 900 seconds of staleness. It does not make the response fresh for 1,200 seconds, and it does not promise that a cache will store it. RFC 5861 describes errors for this extension as responses that would otherwise be 500, 502, 503, or 504.

NGINX supports both stale-if-error and stale-while-revalidate from upstream Cache-Control fields. Its documentation notes that this header-based permission has lower priority than the parameters configured in proxy_cache_use_stale. That ordering matters: a broad proxy rule can outlive or override the narrower intent expressed by an application.

Choose policy ownership deliberately. An application-owned header can travel with each response and vary by resource. An NGINX rule can provide one operational policy even when an upstream cannot emit the extension. Mixing them is valid, but only if the effective priority is reviewed rather than assumed.

A narrow configuration for public pages

The following sketch is intentionally limited to an anonymous public path. Its durations are examples, not recommended universal values, and it has not been presented as this site's production configuration.

# http context
proxy_cache_path /var/cache/nginx/public
    levels=1:2
    keys_zone=public_pages:10m
    max_size=1g
    inactive=60m
    use_temp_path=off;

server {
    location /public/ {
        proxy_pass http://app_backend;

        proxy_cache public_pages;
        proxy_cache_methods GET HEAD;
        proxy_cache_valid 200 5m;
        proxy_cache_revalidate on;
        proxy_cache_lock on;

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

        add_header X-Cache-Status $upstream_cache_status always;
    }
}

proxy_cache_background_update on starts a background subrequest to update an expired entry while the client receives the stale one. NGINX requires stale use during updating for that behavior. This solves a different problem from stale-if-error: background update hides refresh latency, while stale-on-error handles a failed attempt to reach or use the upstream.

proxy_cache_lock on also has a separate job. It allows one request at a time to populate a new cache element for a key while peers wait, reducing a burst of equivalent misses reaching the upstream. It does not create stale content, and it cannot help the first request if no usable entry exists.

The NGINX caching guide explains these controls together, but a real deployment still needs its application rules. Upstream Cache-Control, Set-Cookie, Vary, authorization, and the cache key all affect whether reuse is correct. NGINX normally avoids caching responses with Set-Cookie and responses with Vary: *; those defaults are safeguards, not a substitute for classifying routes.

Decide what must never use this fallback

The most important cache rule may be the exclusion list. A shared cache can reuse one stored response for multiple users, so an incorrect boundary can disclose data or show one user's state to another. MDN's Cache-Control reference recommends private for personalized content and explains that no-store prevents storage. RFC 9111 also places specific restrictions on shared caching of requests carrying Authorization.

Do not put login pages, account dashboards, per-user API responses, carts, authorization decisions, or other sensitive state under a broad public cache rule merely because they use GET. A session cookie bypass can be part of a design, but “no cookie happened to be present” is not proof that every representation on the route is public.

Content can be public and still be a poor stale candidate. Consider an urgent security notice, a revoked download, rapidly changing availability, or a page whose old instructions become dangerous after a deployment. For those resources, a visible error may be more truthful than an apparently normal but outdated response. Directives such as no-cache, must-revalidate, and no-store communicate stricter requirements; RFC 9111 prohibits serving stale when an applicable protocol directive forbids it.

Make fallback visible before relying on it

A successful 200 can hide an unhealthy origin. NGINX exposes the variable $upstream_cache_status, whose possible states include HIT, MISS, EXPIRED, REVALIDATED, STALE, and UPDATING. The example publishes it as X-Cache-Status for diagnosis. If exposing internal cache state publicly is undesirable, put the value in an access log instead.

A safe test needs more than nginx -t. Syntax validation cannot prove the cache policy. In a staging environment or controlled maintenance window:

  1. Request a known public URL and confirm that an eligible response enters the intended cache.
  2. Request it again and observe the expected cache status.
  3. Wait until it becomes stale, then make the test upstream return one specifically configured failure.
  4. Confirm the response body is the known older representation and the status reports STALE, rather than assuming any 200 proves fallback.
  5. Repeat with a cold URL and a private route; neither should receive the public stale object.
  6. Restore the upstream and verify that revalidation or replacement returns the cache to current content.

Also test the cache key dimensions that matter: host, query string, encoding, language, and any field named by Vary. Failure behavior is only as safe as the response-selection behavior that precedes it.

The trade is useful because it is limited

Stale content can reduce the visible impact of a short application failure, but it does not repair the application, preserve write operations, or guarantee that every URL remains available. It can also delay discovery if monitoring watches only client status codes. Origin health and stale responses therefore need separate signals.

The decision is easier when phrased per resource: How old may this representation become before an error is more honest? Which failures justify that exception? Can the same stored response safely serve every request mapped to its key? How will an operator know that the exception is active?

For stable, anonymous articles or documentation, a short and observable stale window may be a reasonable continuity tool. For personal, sensitive, revocable, or quickly changing state, it may be the wrong tool entirely. The goal is not to hide every outage. It is to choose, in advance, where slightly old public information is safer than no information, then keep that permission narrow enough to remain true.

References