cache/purge

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

Force deployment to take effect with cross_version_cache enabled

If cache.cross_version_cache is enabled and you need a deployment to take effect immediately: (1) Call ctx.cache.purge({ purgeEverything: true }) after deploying (simplest approach), or (2) Tag each cached response with the producing version using the version metadata binding, then purge that tag on rollback.

Variants share single purge identity for Vary

Purging by tag or path prefix invalidates every variant of a URL together, so all variants must use the same Cache-Tag values. When using Vary for content negotiation, ensure consistent tagging across all variants.

Purges are scoped to calling entrypoint

Purges are scoped to the entrypoint that calls them. If a purge is needed for cached responses, it must run inside the entrypoint that owns the cached response. A purge issued from a different entrypoint would target that entrypoint's cache instead. When using Durable Objects with caching, the cached entrypoint must expose and call the purge method.

No purge by host mode

There is no purge by host mode for Workers Caching. The cache belongs to the Worker, not to a domain, and the host is not part of the cache key. Use purge by tag, purge by path prefix, or purgeEverything instead.

Purge Workers Cache with ctx.cache.purge()

Your Worker can invalidate its own cache using ctx.cache.purge(). Tags are the most flexible purge mechanism: tag responses with Cache-Tag when returning them, and purge those tags later using ctx.cache.purge({tags: ["tag-name"]}). You can also import cache from cloudflare:workers and call cache.purge({...}) when you do not have ctx in scope, for example from a utility module.

Two ways to call purge: ctx.cache.purge or cache.purge

Workers Caching provides two equivalent ways to trigger a purge from inside a Worker. The first is ctx.cache.purge(...), available on the execution context passed to every handler, which should be used when ctx is already in scope. The second is cache.purge(...), imported from 'cloudflare:workers', which should be used when you want to call purge from code that does not receive ctx, such as a utility module shared across multiple handlers or a framework adapter that does not thread the execution context through its internals. Both forms call into the same API and behave identically.

Purge modes: tags, pathPrefixes, and purgeEverything

The purge() method accepts one of these modes: tags (purges every cached response tagged with one of the given values via Cache-Tag header, scoped per entrypoint), pathPrefixes (purges every cached response whose request path starts with one of the given prefixes, scoped per entrypoint), or purgeEverything (purges every cached response for the entrypoint that called purge(), scoped per entrypoint). purgeEverything is exclusive and cannot be combined with tags or pathPrefixes. Tags and pathPrefixes can be combined in a single call, and the results are unioned (not intersected).

Cache tag requirements and limits

Cache tags must be printable ASCII with no spaces or Unicode characters. Each tag is at most 1024 characters long, and a response can carry up to 1000 tags. Tag matching at purge time is case-insensitive, so 'Foo' and 'foo' purge the same set of responses. Invalid tags are silently dropped at storage time; the response is still cached with the remaining valid tags. The Cache-Tag header value is a comma-separated list of tags and is stripped by Cloudflare before returning the response to clients.

Purge is scoped to entrypoint and Worker

Purging is scoped to the Worker that owns the cache. Within a Worker, purges are further scoped to the entrypoint that called purge(). A Worker cannot reach into another Worker's cache, an entrypoint cannot reach into another entrypoint's cache, and no zone-level purge via the dashboard, API, or Terraform affects Workers Caching content. Tags are scoped to the entrypoint that called purge(), so a tag named 'user-42' applied to responses in two different entrypoints is not invalidated by a single purge({ tags: ['user-42'] }) call. To invalidate the same tag across several entrypoints, call purge() from each entrypoint.

Purge by tag example

Example: attach tags on write by setting the Cache-Tag response header as a comma-separated list (e.g., 'Cache-Tag': 'post,post-123,blog'). Then trigger a purge by calling await ctx.cache.purge({ tags: ['post-123'] }) to invalidate all responses tagged with 'post-123'.

Hierarchical tags for group invalidation

To invalidate groups of related responses in one call, tag each response with multiple tags representing every level of hierarchy it belongs to. For example, a response at /blog/2025/02/hello can be tagged with '_path:/blog/', '_path:/blog/2025/', '_path:/blog/2025/02/', and '_path:/blog/2025/02/hello'. Purging the tag '_path:/blog/2025/' then invalidates every cached response whose URL starts with '/blog/2025/'.

Version-specific purging with cross_version_cache

By default, Workers Caching partitions the cache by Worker version, so each deployment starts from a cold cache and version-specific purging is unnecessary. This applies only when cross_version_cache is enabled in wrangler.json, which allows cached responses to be shared across versions. In that case, tag each response with the version that produced it (using the version metadata binding CF_VERSION_METADATA) and purge that tag later (e.g., 'Cache-Tag': 'post,post-123,v:VERSION_ID'). When you want to invalidate everything a specific version wrote, purge the version tag (e.g., await ctx.cache.purge({ tags: ['v:VERSION_ID'] })).

Purge by path prefix

pathPrefixes invalidates every cached response whose request path begins with one of the given prefixes. Entries in pathPrefixes are paths, not full URLs. A prefix must not include a scheme, host, query string, or fragment. A leading slash is optional ('/images' and 'images' are treated the same) but recommended for clarity. To invalidate a single cached URL, pass its path as a single-element pathPrefixes array (e.g., await ctx.cache.purge({ pathPrefixes: ['/blog/2026/hello-world'] })). Because pathPrefixes matches on the start of the request path, passing the full path matches only that path plus any paths that happen to extend it (e.g., '/blog/2026/hello-world-2'). For exact-match semantics with no risk of over-purge, use a tag instead.

Purge everything invalidates all cached responses

Calling await ctx.cache.purge({ purgeEverything: true }) invalidates every cached response stored by the calling entrypoint. This should be used sparingly because purging everything causes all subsequent requests to miss the cache until they can be re-filled, which temporarily increases load on the Worker and any upstream services it calls.

Purge propagation and return value

Purges triggered by ctx.cache.purge() use Cloudflare's Instant Purge infrastructure and propagate globally with the same guarantees as zone-level purges. The purge() method resolves to a result object with a 'success' boolean and an 'errors' array. On failure, each error in 'errors' carries a numeric 'code' and a human-readable 'message' that can be logged or surfaced to the caller.

Purge rate limits

purge() uses the same rate-limiting system as Cloudflare's zone purge API. Rate limits depend on the account's plan (refer to Availability and limits in the Cache documentation). When the purge is rate-limited, success is false and errors contains an entry describing the rejection.

Purge after write pattern

The recommended pattern is to purge after a write by calling ctx.cache.purge() at the end of any handler that mutates data. For example, after a POST request that updates data in D1, KV, or an origin, call ctx.cache.purge({ tags: ['post-123', 'post-list'] }) to invalidate every cached response tagged for that post.

Purging assets cached by Worker with single-file purge

When using single-file purge to purge assets cached by a Worker, purge the URL that is in the fetch request, not the end user URL. For example, if a Worker runs on https://example.com/hello and makes a fetch request to https://notexample.com/hello, purge https://notexample.com/hello (the asset in the fetch request), not the end user URL. Purging the end user URL will not work because that is not the URL that cache sees.

Single-file purge decision tree for Worker-cached assets

To purge an asset cached by a Worker: (1) Determine if the fetched domain is an active zone on Cloudflare. (2) If no, purge the URL from the original (Worker's) zone. (3) If yes, determine if the domain is proxied (orange-clouded) through Cloudflare. (4) If not proxied, purge from the original zone. (5) If proxied, determine if you own the domain. (6) If you own it, purge from that domain's zone. (7) If you do not own it, you cannot purge the asset — only the owner can.

Purging Cache API assets locally with cache.delete

Call cache.delete within a Worker to invalidate the cache for the asset with a matching request variable. Assets purged in this way are only purged locally to the data center the Worker runtime was executed in.

Purging Cache API assets globally

To purge assets stored in the cache through Cache API operations globally, use standard cache purge options. All assets on a zone can be purged using the Purge Everything cache operation, which removes all assets associated with a Cloudflare zone from cache in all data centers regardless of the method set. Cache Tags can be added to requests dynamically in a Worker by calling response.headers.append() and appending Cache-Tag values. Once set, those tags can be used to selectively purge assets from cache without invalidating all cached assets on a zone.

Custom cache key purge limitation

It is not currently possible to purge a URL that uses a custom cache key set by a Worker. Instead, use a custom key created via Cache Rules, or purge your assets using purge everything, purge by tag, purge by host or purge by prefix.

Purge cache in Miniflare

Use the purgeCache() method on a Miniflare instance to programmatically purge cache entries. Calling await mf.purgeCache() purges the default cache and returns the number of entries purged. Calling await mf.purgeCache("cache-name") purges a specific named cache.

Miniflare cache purge examples

Examples of purging cache in Miniflare: ```js const mf = new Miniflare({ /* options */ }); // Purge the default cache and get the number of entries purged const count = await mf.purgeCache(); console.log(`Purged ${count} entries`); // Purge a specific named cache await mf.purgeCache("my-named-cache"); ```

Give your agent this brain