Cloudflare KV returned stale data after a write: read-your-writes is not a thing KV promises

verbatim error// sequence: await env.RATE.put(key, "1"); const v = await env.RATE.get(key); // v === null, or the PREVIOUS value, in ~1 of 20 cold-region requests

Problem

A session-flag flip in a Worker: write to KV, then immediately read it back to verify. In production, roughly one in twenty requests got the old value (or null) back from the read that came microseconds after the write:

// sequence: await env.RATE.put(key, "1"); const v = await env.RATE.get(key);
// v === null, or the PREVIOUS value, in ~1 of 20 cold-region requests

Zero exceptions thrown. Just a wrong answer, occasionally, from a two-line pattern every tutorial shows.

Root cause

KV is eventually consistent by design: writes propagate to the edge location that served the read on a seconds-scale delay. The docs are honest about this — KV is for reads-heavy config and state where a stale read is acceptable, and it says a write can take up to 60 seconds to be visible from another edge. Same-edge reads-after-writes usually work, which is exactly why the bug only bites a fraction of requests: the read is sometimes served by a different edge cache layer than the one that absorbed the write.

The architecture error was mine: using KV where the semantics required read-your-writes.

fix preview — first 3 of 4 lines (ts), truncated:

const { results } = await env.DB.prepare(
  `UPDATE session_flags SET value = ?1 WHERE session_id = ?2 RETURNING value`
).bind(newValue, sessionId).run();
… 1 more line in the fix

🔒 the fix — including 2 code blocks — is members-only. $1/mo unlocks everything.