skip to content

Why is a response stored with cache.put() in a Cloudflare Worker served in only one data center, and how do you clear it everywhere?

level: middleimportance: should knowfreq 40%

answer

  1. think about where the Worker ran
  2. no replication, no upper tier
  3. delete() is just as local
  4. tag before you store

basics

~20 s

The Cache API in a Worker writes only to the data center that ran it: entries never replicate and cache.put() skips Tiered Cache. cache.delete() is equally local, so clearing every location needs a zone purge by Cache-Tag or Purge Everything.

solid answer

~40 s

The Cache API reads and writes the cache of the data center running that invocation, and its contents never replicate elsewhere. `cache.put()` is also not compatible with Tiered Cache, so no upper tier holds the entry and each location fills its own copy, which lowers the hit ratio for long-tail keys. `cache.delete()` has the same scope: `true` means this data center had the entry and removed it, nothing more. To clear every location I use a zone purge: Purge Everything clears all of the zone's cached assets in every data center, and purge by tag works if I put a `Cache-Tag` header on the response before storing it. For origin-backed content I prefer `fetch()` with `cf` options, which does go through Tiered Cache.

go deeper

for a junior

Remember that the Cache API is local to one data center: what one location stores, another location does not see.

for a middle

Explain why cache.put() does not take part in Tiered Cache, what cache.delete() returns, and which zone purges reach every data center.

for a senior

Diagnose regional misses and failed invalidations from the per-location model, and design keys, tags and lifetimes so a stale copy can always be removed or outlived.

for a principal

Weigh a per-location cache against a tiered or globally replicated store for each dataset, and decide who may run zone-wide purges and how often.

## Where a cache.put() entry lives Cloudflare runs its cache in every data center of its network. The **Cache API** in a Worker (`caches.default` or a cache from `caches.open()`) reads and writes **only the cache of the data center that is running that Worker invocation**. The docs say it plainly: the contents of the cache do not replicate outside the originating data center. A `GET /rates` response stored by a visitor's request in one city does not exist in another city until a request there stores it too. Three consequences follow from that one rule: - `cache.match()` looks **only locally**. A miss here says nothing about other locations. - `cache.put()` writes **only locally**, and it is **not compatible with Tiered Cache**: no upper tier ever holds the entry, so a lower-tier miss cannot be answered by an upper tier. - `cache.delete()` removes **only the local copy**. It resolves to `true` if this data center held the entry and has now removed it, and to `false` if this data center did not have it. ## What that does to hit ratio and origin load - Every data center that serves the Worker **fills its own copy**, so an expensive build runs once per location per lifetime, not once per network. - **Long-tail keys** (many URLs, each requested rarely) hit poorly, because each location sees too few requests to reuse its copy. - When a Worker proxies an origin, a `fetch()` subrequest **does** go through the zone cache and Tiered Cache when that is enabled, so upper tiers shield the origin. For origin-backed content, `fetch()` with its `cf` cache options is usually the better tool; the Cache API fits responses the Worker builds itself. ## Removing an entry everywhere | Action | Reach | Notes | |---|---|---| | `cache.delete(key)` in a Worker | the data center that ran it | returns `true` or `false` for that location only | | Purge by tag | every data center | needs a `Cache-Tag` header on the response passed to `put()` | | Purge Everything | every data center | clears all of the zone's cached assets, whatever stored them | | Waiting for expiry | every data center, eventually | each copy expires on its own `Cache-Control` lifetime | The docs add a caution: not every purge endpoint works for assets stored through the Cache API. **Plan the purge before you write the entry**: tag what you store, and keep lifetimes short enough that waiting is an acceptable fallback. ## Designing for a per-location cache 1. **Tag every stored response** with a `Cache-Tag` that matches how you will invalidate it (`rates`, `rates-eur`). 2. **Version the key** when the format changes (`/v2/rates`), so old copies are never matched again even before they expire. 3. **Keep lifetimes honest**: a short `s-maxage` bounds how long a stale copy can survive in a location you cannot reach with `cache.delete()`. 4. **Pick the store by the data**: per-location reuse of a computed response suits the Cache API; data that every location needs belongs in a globally replicated store such as Workers KV. ## Reading the symptoms A per-location cache produces a recognisable pattern, and knowing it saves a long investigation: - **Hit ratio varies by region.** Busy locations reuse their copies; quiet ones rebuild almost every time, because few requests arrive there within one lifetime. - **Origin or upstream load does not fall as far as expected.** Each new location pays one full build, and a fresh deploy that changes the key pays it again everywhere. - **Stale content lingers in some places only.** After a fix, a location that stored the old response keeps serving it until its own copy expires, while locations that never stored it already show the new one. ## Common traps - Load-testing from one machine and seeing hits, then wondering why visitors in other regions miss: they are on **other data centers**. - Building an admin "invalidate" endpoint on `cache.delete()` and believing it worked because it returned `true`: it cleared **one** location. - Expecting **Smart Tiered Cache** or another Tiered Cache topology to raise the Cache API's hit ratio: it does not apply to `cache.put()` entries. The Cache API is therefore a **local, explicit** cache: cheap and fully under the Worker's control, with global reach only through a zone purge or through expiry.

  • Why does a fetch() subrequest benefit from Tiered Cache when cache.put() does not?
    `fetch()` reads through the zone cache, and with Tiered Cache enabled a lower-tier miss asks an upper-tier data center before going to the origin, so one fill serves many locations. `cache.put()` and `cache.match()` touch only the local data center's cache, so upper tiers never see those entries. For content that comes from an origin, `fetch()` with `cf` cache options gets the better hit ratio.
  • What does cache.delete() returning false tell you?
    Only that the data center running this invocation had no entry for that key when it ran. Other locations may still hold copies and keep serving them until they expire or a zone purge removes them. Treat `cache.delete()` as a local tidy-up, never as proof that the network is clean.

Each data center is a branch office with its own pinboard. A Worker pins a notice only on the board of the branch where it is working, and taking a notice down there leaves every other branch's copy in place; only a recall from head office, a zone purge, clears every board at once.

  • cache.put() entries replicate to every Cloudflare location within seconds
  • cache.delete() from one request purges the entry across the whole network
  • Turning on Smart Tiered Cache lets upper tiers serve Cache API entries
  • A Cache API entry can only disappear by waiting out its TTL
  • cache.delete() returning true proves no location still holds the entry