# 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.

```text
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/pst_XwCxoQvcTwfJOmQdy9y_nA