Cache invalidation in KV: the problem that no one solves elegantly

Phil Karlton said there are only two hard things in computer science: cache invalidation and naming things. KV makes the first one even more difficult, because you don't control when the invalidation arrives at each presence point.

Deleting a key in KV does not immediately remove it from the world. The delete goes to the central store and propagates to the PoPs with the same eventual consistency dynamics as the writes: up to 60 seconds to reach all points of presence. During this window, PoPs that have not yet received the delete continue serving the old value to any incoming requests. You don't know which PoPs received it and which didn't. There is no way to force immediate propagation.

This makes cache invalidation in KV a design issue, not an operation issue. You don't solve it with an "invalidate now" button — you solve it by choosing a key model that minimizes the impact of propagation delay.

Versioned keys: the most robust solution

The most solid standard for content that needs to be invalidated is to maintain an explicit indirection between the logical name of the data and the physical key where it is stored.

Instead of writing a page's rendered HTML to homepage-html and then deleting it when the content changes, you write it to homepage-html-v42. A second key, homepage-html-version, contains just the string v42. The Worker reads the version key first, constructs the content key name, and fetches the value.

When the content changes, you write the new HTML in homepage-html-v43 and update homepage-html-version to v43. The old key does not need to be deleted immediately — it simply stops being referenced. Its storage cost continues to exist until you cleanup, but the invalidation inconsistency is no longer a problem: any PoP that received the homepage-html-version update will already get the new key. Old content is only served to PoPs that have not yet received the version key update, and this happens within the 60 second window regardless of what you do.

The cost of this approach is one extra read per request — first the version key, then the content. For most cases, this cost is irrelevant in terms of latency: the two reads are parallel if the Worker does them with Promise.all, and both arrive from the PoP cache in sub-milliseconds when hot.

Coordinate KV with CDN purge

For content served from the Cloudflare CDN (not directly from the Worker), there is an additional layer of caching above the KV. The CDN may have cached a response generated with an old KV value, and even if the KV already has the new value in all PoPs, the response cached in the CDN will still be served until it expires.

The solution is to coordinate the KV update with a CDN purge. Cloudflare's Cache Purge API allows you to invalidate specific URLs or cache tags via API. You write the new value to the KV and, in the same administrative operation, call the purge API for the affected URLs. From the perspective of customers passing through the CDN, the new response appears immediately after the purge — regardless of how many PoPs are still propagating the KV value.

This pattern requires that you control the content update process and have access to the purge API. For CMS flows where a publisher publishes content, it's a reasonable integration: the publish webhook updates the KV and triggers the purge.

Stale-while-revalidate with waitUntil

The stale-while-revalidate pattern serves potentially outdated content while triggering a background update. In the context of Workers, ctx.waitUntil() allows executing asynchronous work after the response is sent to the client.

Typical implementation: Worker reads the current KV value and serves immediately. At the same time, it triggers via ctx.waitUntil() a function that checks whether the value needs to be updated — consulting a source, for example — and writes the new value to the KV if necessary. The client receives the response without waiting for the update. The next request may already receive the new value, depending on when the propagation completes.

The tradeoff is explicit: you trade zero latency to the client for a window in which outdated content can be served. For most content caching scenarios, this tradeoff is acceptable. For data where staleness has operational consequences — prices, stock availability, access permissions — the standard is not appropriate.

TTL as a replacement for explicit invalidation

For cases where precise invalidation is not necessary, TTL is the simplest mechanism. KV supports expirationTtl (seconds from now) and expiration (Unix timestamp) defined at the time of writing.

A feature flag with a TTL of 60 seconds automatically expires. The next request after expiration will fetch the central store and return the most recent value — or an empty value, which the Worker can interpret as "flag disabled". You don't need to explicitly delete or track the state.

For content with predictable refresh frequency, refresh cycle-aligned TTL eliminates the need for active invalidation. A report generated every time can have a TTL of 3600 seconds. The oldest possible value any user will see is approximately one hour, and this is a design choice, not a consistency flaw.

What doesn't work: immediate delete and rewrite

A pattern that appears frequently and does not solve the problem is to delete the old key and write the new one in sequence. This does not eliminate the inconsistency window — the two operations propagate independently to the PoPs. A PoP may receive the delete but not yet have received the new write, and during that window it will return not-found for that key. Depending on how the Worker handles this case, this could result in an error or unexpected fallback.

Deleting and rewriting have double the propagation operations with triple the possible intermediate states: old, not found, new. Versioned or TTL keys are always preferable.

How eventual consistency changes design

The healthiest pattern for working with KV is to accept eventual consistency as a feature of the system, not as a limitation to be worked around. This means designing flows where a window of up to 60 seconds of inconsistency is tolerable, and using different tools when it is not.

For data that requires immediate consistency across all PoPs, KV is not the right tool. D1 with readings directed to the primary, or Durable Objects for state with serialized access, cover cases where the KV eventual consistency model does not work.

Elegant invalidation in KV is one that does not need to happen urgently — because the system design was made to tolerate the propagation window. Any attempt to force immediate consistency will work against the architecture, not with it.