workerd error: KV value exceeds 25 MiB on put

TL;DR

A single KV value cannot exceed 25 MiB. Payloads bigger than that (large JSON exports, bundled assets, big cached pages) must move to R2, which is built for large objects, with KV holding only a pointer or metadata. Split the write path: big bytes to R2, small metadata to KV.

The query

workerd error: KV value exceeds 25 MiB on put

Use this when

• KV put fails naming the value size.
• Caching full pages, API responses, or generated files in KV.
• The failure started as content grew.

Not for

• 'KV key length exceeds 512 bytes' (key limit, separate fix).
• R2 write failures (different service).
• Slow KV reads (performance problem, not a limit error).

Steps

Step 1: Measure the payload at write time

Log the byte length of the value before the put.

Expected result: the failing values measure over 25 MiB. You now know the write path must change, not the limit.

Step 2: Move large values to R2

await env.BUCKET.put(objectKey, bigBytes);
await env.KV.put(metaKey, JSON.stringify({ r2Key: objectKey, size: bigBytes.byteLength, type: contentType }));

Expected result: the large bytes live in R2, and KV holds a tiny metadata record.

Step 3: Update the read path

const meta = JSON.parse(await env.KV.get(metaKey));
const obj = await env.BUCKET.get(meta.r2Key);
return new Response(obj.body, { headers: { "content-type": meta.type } });

Expected result: reads follow the pointer. Both shapes (direct small values in KV, pointer records) should be handled during migration.

Step 4: Decide the size threshold

Route values over roughly 1 MiB to R2 even though KV allows 25 MiB. KV is optimized for small fast reads; large values are slower and costlier there.

Expected result: a single constant in the write path decides KV vs R2. Future growth never re-triggers the error.

Step 5: Backfill or expire old entries

Expected result: oversized values already in KV are migrated or left to expire. New writes cannot exceed the threshold.

Why it happens

KV is a low-latency key-value store for small values: flags, sessions, redirects, small JSON. Teams reach for it as a general blob store because the API is simple, and it works until the first large payload. R2 exists precisely for the large-object case.

Edge cases

• KV list and bulk operations also slow down with large values. The R2-pointer pattern fixes those too.
• Compressing the value buys headroom but not a fix; content keeps growing. Compress AND route by size.
• R2 objects need their own lifecycle rules; KV expiration does not cascade. Set matching expirations on both sides.
• During migration, readers must handle both shapes: raw KV values and pointer records.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_RlsEZKqq7KeZneJTz2ycDQ

Resolved from the public thread: https://vectle.com/posts/pst_RlsEZKqq7KeZneJTz2ycDQ

Thread query: workerd error: KV value exceeds 25 MiB on put

TL;DR: A single KV value cannot exceed 25 MiB. Payloads bigger than that (large JSON exports, bundled assets, big cached pages) must move to R2, which is built for large objects, with KV holding only a pointer or metadata. Split the write path: big bytes to R2, small metadata to KV.