Question
Change in proxy_cache_use_stale updating behavior with proxy_cache_background_update enabled from nginx 1.19.0 onward
Nia Indigo
0 reputation · 28 Mar 2026, 12:26 UTC
78.2K views1
Loading…
0 reputation · 28 Mar 2026, 12:26 UTC
When both proxy_cache_use_stale updating and proxy_cache_background_update are enabled, nginx must decide whether to return the existing stale cache entry immediately or to wait for the asynchronous background fetch to finish before responding. The documentation notes that the stale response is served only if the request arrives before the background update finishes, but it does not specify the exact timing boundary or any internal race‑condition handling mechanism. This leaves an unresolved decision about how nginx treats requests that arrive shortly after the background update has started.
Understanding this behavior is important for configuring cache‑staleness policies across nginx versions, especially after the default change in 1.19.0 that removed updating from proxy_cache_use_stale unless explicitly added.
Does nginx serve the stale response if the request arrives after the background update has started but before it completes? Is there a configurable threshold or internal timer that determines the cutoff? How does this behavior differ between nginx releases prior to 1.19.0 and those at 1.19.0 or later?
34775 reputation · 29 Mar 2026, 00:12 UTC
When proxy_cache_background_update is enabled, nginx will serve the existing stale cache entry for any request that arrives while a background update subrequest is in progress, regardless of whether the proxy_cache_use_stale directive includes the updating flag. There is no configurable timer or threshold; the decision is based solely on the internal “updating” state of the cache entry.
nginxproxy_cache_background_update and proxy_cache_use_stale updating changed: the updating flag is ignored and treated as implicitly allowed when background updates are on.updating flag must be explicitly present in proxy_cache_use_stale to obtain the same behavior; without it, nginx would not serve stale while updating (it would either wait for a synchronous fetch or return an error according to other stale conditions).nginx -v. If the version is 1.19.0 or higher, the implicit updating behavior applies.proxy_cache_background_update on; is set in the relevant location or server block.updating keyword from proxy_cache_use_stale (keep other flags if needed) and reload nginx.proxy_cache_valid time) and make a request that triggers a cache miss.If stale responses are not served during the update, double‑check that proxy_cache_background_update is indeed enabled and that the nginx version is >= 1.19.0.
Use comments to ask for clarification. Post a solution as an answer.
34,775 reputation · 28 Mar 2026, 12:55 UTC
When a stale entry is being refreshed, nginx marks it with an internal updating flag. Any request that arrives while that flag is set will immediately get the stale body, regardless of whether the request started before or after the subrequest was launched. The flag is cleared only when the background fetch finishes (successfully or with an error). Because the decision is purely state‑based, there is no configurable timeout that can shift the cutoff. If proxy_cache_use_stale does not include updating (the default after 1.19.0), concurrent requests will instead wait for the cache lock (up to proxy_cache_lock_timeout) and may return a 504 if the lock expires.
Thus, the “race” you’re concerned about is resolved by the lock mechanism: the first request triggers the update, subsequent ones either get the stale copy or wait, but none of them are delayed by an internal timer.