A team proposes keeping a per-user request counter in Workers KV, incremented on every request; what breaks in production, and where should the counter live instead?
answer
- how often one key may change
- read, add one, write back
- what other locations have cached
- writes cost more than reads
basics
~20 sA Workers KV key accepts one write per second, so a busy user's increments start failing with 429 errors. A get-then-put is not atomic, so concurrent requests overwrite each other, and stale reads in other locations lose more. Counters belong in a Durable Object.
solid answer
~50 sFour things break. Workers KV allows one write per second to the same key, and faster writes reject with `KV PUT failed: 429 Too Many Requests`. Reading the count with `get()` and writing `n + 1` with `put()` is not atomic: two requests read the same value and the last write wins, so increments vanish. Reads in other locations can be 60 seconds or more out of date, so a user whose requests land in several locations restarts from old values. And every request becomes a billed write, which on the Paid plan costs ten times a read and on the Free plan stops at 1,000 writes a day. Local development does not enforce the write limit, so the design looks fine until production. The counter belongs in a Durable Object, one per user, whose storage updates are serialised and strongly consistent.
code
javascript · 10 lines// Anti-pattern: a per-user counter in Workers KV.
export default {
async fetch(request, env) {
const userId = new URL(request.url).searchParams.get("user") ?? "anon";
const key = `counter:user:${userId}`;
const n = Number((await env.FLAGS.get(key)) ?? 0);
await env.FLAGS.put(key, String(n + 1)); // can reject with 429; races lose increments
return Response.json({ count: n + 1 });
},
};go deeper
Remember that a Workers KV key takes at most one write per second and that KV has no atomic increment.
Explain the 429 error, why get-then-put loses updates under concurrency, and how propagation makes other locations read old counts.
Diagnose missing or bouncing counts as lost updates and write-limit rejections, show why local tests miss them, and move the counter to a Durable Object.
Use the counter proposal to set the rule: KV holds data written rarely by one writer, and anything incremented per request goes to a store with atomic updates.
## The proposal The reserved scenario has a feature-flag and site-configuration store in Workers KV that works well: it is read on every request and changed a few times a day. Someone suggests reusing the same namespace to count requests per user, for usage display or a soft quota: ```javascript const key = `counter:user:${userId}`; const n = Number((await env.FLAGS.get(key)) ?? 0); await env.FLAGS.put(key, String(n + 1)); ``` The code is short and passes a local test. In production it fails in four separate ways. ## Failure 1: one write per second per key Workers KV accepts **at most one write per second to the same key**, on every plan. Writes made to the same key within one second cause rate-limiting errors, and the `put()` promise rejects with: ```plaintext KV PUT failed: 429 Too Many Requests ``` A user who loads a page that triggers several requests at once, or a script calling the API, crosses that rate immediately. If the code does not catch the rejection, the request fails; if it catches and ignores it, the count is silently wrong. Retrying with exponential backoff, as the documentation recommends for handling these errors, only spreads the writes out; it cannot raise a sustained rate above one per second. ## Failure 2: read-modify-write is not atomic KV has **no increment or compare-and-set operation**. When two requests run the snippet at the same time, both read `n`, both write `n + 1`, and one increment is lost; concurrent writes to one key end with the **last write winning**. Twenty concurrent requests against the snippet in local development, where no write limit applies and every write succeeds, can end with a stored count of 6 rather than 20. The documentation says directly that KV is not ideal where atomic operations or read-and-write transactions are needed. ## Failure 3: stale reads across locations Reads are served from each location's cache, and another location's write can take 60 seconds or more to be seen. A user whose requests reach two locations, for example on a mobile network, gets increments based on old values in each, so the counter jumps back. Lowering `cacheTtl` to its 30-second minimum shortens the window but does not close it. ## Failure 4: cost and quotas | Plan | Reads | Writes | |---|---|---| | Free | 100,000 per day | 1,000 per day | | Paid | 10 million a month included, then $0.50 per million | 1 million a month included, then $5.00 per million | Turning every request into a write makes a read-optimised store write-bound. On the Free plan, writes to different keys stop at 1,000 a day and further writes fail; on the Paid plan each write costs ten times a read. ## Why local testing hides it `wrangler dev` simulates KV locally, but it does not reproduce the one-write-per-second limit or global propagation: parallel writes to one key all succeed there. Only the lost-update race shows up locally, and only under concurrent load. ## Where the counter belongs The KV documentation points write-heavy, per-key workloads to **Durable Objects**: - Address one object per user, for example with `env.COUNTERS.getByName(userId)`. - The object processes its requests one at a time, so `count + 1` cannot interleave, and its storage is strongly consistent. - A single object has a soft limit of about 1,000 requests per second, far above KV's one write per second per key. How to build that object, its storage API and when to shard it are covered in the Durable Objects lessons. If the counter exists only to enforce a request quota, Cloudflare's rate-limiting features may fit better, and they have their own lesson. ## What KV is still good for here KV stays the right home for the flags and configuration the counter would have shared a namespace with. A useful split is: 1. Flags and settings in KV, written by one admin process. 2. Per-user counters in Durable Objects. 3. If a dashboard needs the counts at the edge, a periodic job copies a summary into KV, well under one write per second per key. Spreading one counter across many KV keys, one per request, avoids the write limit but leaves the counts stale, makes summing them a series of billed `list()` calls, and keeps the cost of a write per request.
- In Workers KV, would retrying the 429 with exponential backoff make the counter correct?No. Backoff turns some rejected writes into later successes, but the key still takes at most one write per second, so a sustained higher rate can never be met. It also does nothing for the lost-update race or for stale reads in other locations: each retry writes a value computed from a possibly old read.
- In Workers KV, is it acceptable to keep a counter that a scheduled job updates once a minute?Yes. One write a minute to a key is far below the one-write-per-second limit, there is a single writer so nothing races, and readers can tolerate a value that is a minute or so old. That is KV's documented sweet spot: written rarely by one process, read often everywhere.
- In Workers KV, why do the counter's bugs not appear under wrangler dev?Local mode simulates KV in one process: it does not apply the one-write-per-second limit and has no other locations with cached copies. Parallel writes to one key all succeed locally. Only the lost-update race can appear, and only if the local test sends concurrent requests.
- KV handles counters fine because reads are fast everywhere
- Retrying 429 errors with backoff makes high-rate writes to one key safe
- Lowering cacheTtl to 30 seconds makes read-then-write increments accurate
- If it works under wrangler dev, the per-key write limit is not a problem
- KV has an atomic increment operation for counters
- Writes cost the same as reads, so a write per request is cheap