workerd error: websocket message too large

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