cache/debugging

10 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Cf-Cache-Status header for debugging cache behavior

The Cf-Cache-Status response header is the primary debugging tool for Workers Caching. Every response carries this header, and its value indicates exactly what happened for that request. Check this header first when caching is not behaving as expected.

Workers Caching operates separately from zone-level cache

Workers Caching is your Worker's cache and operates independently from zone-level cache controls and dashboards. Zone-level settings will not affect what Workers Caching stores or serves. When debugging, look at your Worker's traces and responses, not zone-level cache dashboards.

Caching not enabled - missing Cf-Cache-Status header

If Cf-Cache-Status header is not present in responses, ensure wrangler version is 4.69.0 or above, and that wrangler.toml or wrangler.jsonc contains 'cache.enabled = true' for that worker.

Debugging stale cached content

If origin data changed but requests still return stale content: (1) Check the TTL - the response stays cached for max-age seconds and may be within its freshness window, (2) Purge affected responses using ctx.cache.purge() with tags or path prefix, (3) Add tags at write time - if you did not set Cache-Tag headers, add them, deploy, and once new entries are written they become purgeable.

Cf-Cache-Status UPDATING constantly appears

UPDATING means the response was served from cache while stale and your Worker is running in the background to refresh it. This is expected with stale-while-revalidate. If UPDATING appears more often than expected: (1) Your max-age is shorter than request arrival rate - every request after max-age elapses triggers revalidation, (2) With max-age=0, stale-while-revalidate=<large>, every request triggers revalidation; this is 'always serve from cache' behavior, not 'don't run the Worker'.

Cf-Cache-Status UPDATING never appears - conditions

UPDATING is emitted only when all of the following are true: (1) A cached entry exists and is past its freshness window (stale), (2) The response carries stale-while-revalidate=N and the request arrives within N seconds of the entry going stale, (3) The response does not carry s-maxage, must-revalidate, or proxy-revalidate. If any of these is false, requests for stale entries fall through to inline revalidation instead, producing EXPIRED or REVALIDATED.

Why Cf-Cache-Status UPDATING does not appear

Common reasons UPDATING does not appear: (1) No stale-while-revalidate directive on the response - default SWR window is 0, so without explicit directive every stale request is foreground-revalidated, (2) s-maxage, must-revalidate, or proxy-revalidate is present - per RFC 9111 §4.2.4 these forbid serving stale content, so Cloudflare disables stale-while-revalidate when any is present; use max-age instead, (3) SWR window has elapsed - requests after the SWR window revert to inline revalidation.

Cf-Cache-Status STALE means Worker error occurred

STALE means Cloudflare served a previously cached response because your Worker errored on the request that would have refreshed it. For example, the Worker threw, timed out, or returned a 5xx response. This is stale-if-error behavior. Check the Workers observability dashboard for errors on the requests that should have produced a fresh response.

STALE status masks real Worker failures

When clients see Cf-Cache-Status: STALE, it means your Worker is failing on cache fills or revalidations but clients are not seeing the failure. To distinguish STALE from normal HIT in client-side observability, log Cf-Cache-Status alongside the response - STALE is the only signal that the Worker is failing.

Primary debugging surfaces for Workers Caching

At launch, the primary debugging surfaces are the Cf-Cache-Status response header and per-invocation cache-hit information in the Workers observability dashboard.

Give your agent this brain