cache/limitations

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

Response too large to cache produces MISS status

If a response is too large to cache, Cloudflare does not store it and Cf-Cache-Status: MISS appears on every request even though the response otherwise looks cacheable. At launch all Workers Caching responses are subject to the Free plan size limit - refer to Response size limits in the limitations documentation.

HTTP methods supported by Workers Caching

Only GET and HEAD requests are cached by Workers Caching. POST, PUT, PATCH, DELETE, and other methods always invoke the Worker without caching. GET and HEAD for the same URL share a single cache entry.

HEAD requests and cache population

When a HEAD request arrives on a cold cache, it is converted to a GET internally so the cache is populated with the full asset. This ensures the cache entry is available for subsequent requests.

Caching non-idempotent requests

To cache responses to non-idempotent requests, do so explicitly in the Worker by hashing the request body into a synthetic URL and making an internal GET subrequest.

WebSocket upgrades bypass cache

WebSocket upgrade requests (GET with Upgrade: websocket header) bypass the cache and always invoke the Worker. WebSocket sessions are stateful and are not a meaningful unit of caching.

Custom RPC methods bypass cache

Only fetch() invocations on a WorkerEntrypoint go through Workers Caching. Custom RPC methods like ctx.exports.Backend.getUser(id) bypass the cache and always run the callee, regardless of the entrypoint's cache.enabled setting. To cache RPC work, refactor it to a fetch handler on its own entrypoint.

Status codes never cached

Workers Caching never stores responses with the following status codes, even with explicit Cache-Control directives: 520–526 (Cloudflare failsafe responses) are treated as transient errors and always re-run the Worker. 206 Partial Content returned by the Worker is not stored; Workers Caching expects the Worker to return the full 200 response and does the range slicing itself.

Invocation types that bypass cache

Workers Caching only applies to HTTP requests handled by a fetch handler on a Worker entrypoint. The following invocation types always run without cache involvement: Cron Triggers (scheduled handler), Queue consumers (queue handler), Workflows (workflow step execution), Tail Workers (trace event handlers), and Durable Objects (never cached regardless of handler or method). To cache a Durable Object's HTTP responses, wrap it behind a Worker entrypoint with caching enabled.

Cache pre-warming not available

There is no API to pre-populate the cache with responses generated at build time. A response is only cached once it has been served at least once. For pre-rendered content available to the first requester, use Static Assets.

Cache-Tag limits

Limits on the number, length, and character set of Cache-Tag values for Workers Caching are the same as Cloudflare's zone cache.

Purge rate limits

ctx.cache.purge() uses the same rate-limiting system as the zone purge API.

Cache API not compatible with tiered caching

The Cache API is not compatible with tiered caching. To take advantage of tiered caching, use the fetch API instead.

Cache API local to data center only

Cache API within Workers does not support tiered caching because it is local to a data center. This means that cache.match does a lookup, cache.put stores a response, and cache.delete removes a stored response only in the cache of the data center that the Worker handling the request is in. These methods apply only to local cache and will not work with tiered cache.

Give your agent this brain