workerd error: WebAssembly module exceeds compiled size limit

Not specified by the original author.

TL;DR: Make the WASM module smaller or stop bundling it. Rebuild with size optimizations and strip debug info, and if it is still too big, fetch the module from R2 at runtime and instantiate it from the fetched bytes. The compiled-size cap applies to what ships in the bundle.

workerd error: WebAssembly module exceeds compiled size limit

1. Confirm the module is the problem. Check the deploy error names the WASM module, and measure the module file size in your project. Expected: one .wasm file accounts for most of the bundle weight.

2. Rebuild for size. Compile with size optimization flags, run the optimizer over the output, and strip debug symbols and names. Expected: the .wasm file shrinks substantially, often by half or more.

3. Redeploy with the optimized module. Expected: the deploy succeeds if the module now fits under the cap.

4. If it still does not fit, move the module out of the bundle. Upload the .wasm file to R2, fetch it at runtime, and instantiate from the bytes:

   const res = await fetch(moduleUrl);
   const bytes = await res.arrayBuffer();
   const mod = await WebAssembly.compile(bytes);

   Expected: the bundle stays small, the deploy succeeds, and the module loads on first use.

5. Cache the compiled module in a global so each isolate compiles it once. Expected: first request pays the compile cost, later requests reuse it.

6. Verify cold starts still pass the startup CPU budget with the runtime load in place. Expected: no startup errors in tail, and the WASM-backed path works end to end.

Use this when

• the deploy fails naming a WASM module and the compiled size limit
• adding an image, crypto, or parser library that ships WASM broke a previously working deploy
• the .wasm file is megabytes in size
• you need the WASM functionality but the bundle cannot carry it

Not for this skill when

• the deploy fails on total script size without mentioning WASM (that is the bundle size limit)
• the module loads but traps at runtime (that is a WASM logic bug, not a size limit)
• the error is about WASM compilation time rather than size
• you can replace the WASM dependency with a pure-JS alternative that fits

Variant phrasings

• Cloudflare Worker WASM too large deploy fails
• "WebAssembly module exceeds compiled size limit"
• wasm module size limit workers deploy
• bundle WASM in Cloudflare Worker fails
• workerd wasm compiled size exceeded

Why it happens

The platform caps how large a compiled WASM module inside a worker bundle may be, because big modules cost compile time and memory on every cold start. Debug builds and unoptimized output bloat modules far past what the cap allows. Optimizer builds strip what the cap counts, and runtime loading moves the bytes out of the bundle entirely so the cap no longer applies to them.

Edge cases

• Runtime-loaded modules still cost compile CPU on first use. Budget that against the startup or request CPU limit.
• Fetching the module from R2 on every cold start adds latency. Cache the compiled module in a global per isolate.
• Some WASM toolchains embed the module as base64 in JS. That counts against the bundle too, and base64 inflates size by a third. Keep the .wasm file separate.
• Version the R2 object with the module. A stale cached module after a logic change is a nasty bug to chase.
• Instantiating from fetched bytes requires the bytes to be complete before compile. Do not stream partial bytes into the compiler.

Provenance

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

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

Thread query: workerd error: WebAssembly module exceeds compiled size limit

TL;DR:

Not specified by the original author.

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.

Not specified by the original author.

workerd error: websocket message too large

TL;DR

A websocket message exceeds the size limit. Chunk large payloads into multiple messages with a reassembly protocol, or move bulk data to HTTP/R2 and use the socket for control. Sockets are for messages, not files.

workerd error: websocket message too large

Steps

1. Measure the message size against the limit. Expected: The overage is confirmed.

2. Chunk the payload: split into numbered chunks, reassemble on receipt. Expected: Large data flows as many small messages.

3. Or move bulk transfer off the socket: HTTP upload plus a 'ready' message over WS. Expected: The socket stays light.

4. Add a client-side size check before send. Expected: Oversize sends fail fast locally.

5. Document the message size contract for the protocol. Expected: Both ends agree.

When to use

• websocket sends fail with message too large
• large payloads over WS
• the protocol has no chunking

When not to use

• messages are small (check the actual bytes sent)
• the error is on connection (different problem)
• using a different WS implementation (limits differ)

Tool compatibility

• workerd
• WebSockets

Variant phrasings

• "websocket message too large workerd"
• "ws message too large worker"
• "cloudflare websocket size limit"

Why it happens

Websocket messages have size caps; a single huge message is rejected. Protocols designed on a local machine assume unlimited messages and break at the edge. Chunking (or moving bulk off the socket) is the standard fix, and the protocol needs to define it explicitly.

Edge cases

• the reassembly needs timeouts; a missing chunk must not hang forever
• control messages and data messages should be distinguishable
• backpressure matters: chunked sends can still overwhelm a slow reader

Provenance

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

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

Thread query: workerd error: websocket message too large

TL;DR: A websocket message exceeds the size limit. Chunk large payloads into multiple messages with a reassembly protocol, or move bulk data to HTTP/R2 and use the socket for control. Sockets are for messages, not files.