proxy_cache_use_stale limits for upstream errors and expired content

Answer

Stale responses are served when an upstream request fails with one of the error conditions listed in proxy_cache_use_stale and the object is already present in the cache. The age of a usable stale entry is bounded by proxy_cache_valid (defines how long a response is considered fresh) and, if set, proxy_cache_max_stale (adds an optional grace period beyond freshness). Serving stale for client errors such as 404 or 403 is possible only when those codes are explicitly added to the stale list, but it is generally discouraged in production because it may hide genuine missing‑or‑forbidden resources.

Confirmed facts

• proxy_cache_use_stale accepts the flags: error, timeout, invalid_header, updating, http_500, http_502, http_503, http_504, and off. Any other HTTP status code (e.g., 404, 403) must be added explicitly, e.g., proxy_cache_use_stale error http_403 http_404;.
• The directive does not impose a numeric limit on how many stale responses can be returned; control comes solely from the selected trigger conditions.
• When the updating flag is present, nginx serves the stale copy while a background request fetches a fresh version; the stale entry is replaced upon successful receipt of the fresh response.
• Freshness is determined by proxy_cache_valid (e.g., proxy_cache_valid 200 10m;). After that period, the object becomes "stale". If proxy_cache_max_stale is set (e.g., proxy_cache_max_stale 5m;), nginx may continue to serve the stale entry for up to that additional time; otherwise, stale serving continues as long as the object remains in the cache (subject to proxy_cache_inactive).
• Stale serving is triggered only by upstream failures (error, timeout, invalid_header, updating, or the explicit HTTP status codes listed). Normal expiry of a cached entry does not by itself cause a stale response; the entry is simply considered stale and will be used only when an upstream error occurs.

Likely explanation

Because nginx has no built‑in counter for stale responses, the administrator must rely on the combination of proxy_cache_valid and proxy_cache_max_stale to bound the age of stale data. If proxy_cache_max_stale is omitted, the effective limit is the time the object stays in the cache (governed by proxy_cache_inactive and manual purging). Including client error codes in the stale list expands the set of conditions under which stale may be served, but doing so risks serving outdated "not found" or "forbidden" pages when the upstream has actually removed the resource or changed access rights.

Verification

1. Run nginx -T to dump the effective configuration and confirm the proxy_cache_use_stale line contains the desired flags (e.g., error http_502 http_504).
2. Add a response header such as add_header X-Cache-Status $upstream_cache_status; and request a resource while the upstream is stopped; the header should show STALE for a cached object.
3. To test the age limit, set proxy_cache_valid 200 1m; and proxy_cache_max_stale 30s;, wait 90 seconds, then stop the upstream; nginx should return a 5xx error (or the configured fallback) because the stale entry is now older than the allowed 1 min + 30 s.
4. After any config change, run nginx -t to validate syntax, then reload and observe the new behavior.