# WebSocket close code 1009: Message too large

- **ID:** `api/websocket-close-code-1009-message-too-large`
- **Domain:** api
- **Category:** protocol_error
- **Error Code:** `1009`
- **Verification:** ai_generated
- **Fix Rate:** 78%

## Root Cause

The WebSocket frame or message size exceeds the server's configured maximum payload size, typically 64KB or 1MB, causing the connection to close.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| ws 8.16.0 (Node.js) | active | — | — |
| websockets 12.0 (Python) | active | — | — |
| Tornado 6.4.0 | active | — | — |
| Spring WebSocket 6.1.0 | active | — | — |

## Workarounds

1. **Increase the maximum message size on the server. For Node.js with 'ws': `const wss = new WebSocket.Server({ maxPayload: 1024 * 1024 });`. For Python with 'websockets': `async with websockets.serve(handler, host, port, max_size=2**20):`.** (90% success)
   ```
   Increase the maximum message size on the server. For Node.js with 'ws': `const wss = new WebSocket.Server({ maxPayload: 1024 * 1024 });`. For Python with 'websockets': `async with websockets.serve(handler, host, port, max_size=2**20):`.
   ```
2. **Compress large messages using a binary format like Protocol Buffers or MessagePack before sending over WebSocket. Example: serialize with `msgpack.pack(data)` and send as binary frame.** (85% success)
   ```
   Compress large messages using a binary format like Protocol Buffers or MessagePack before sending over WebSocket. Example: serialize with `msgpack.pack(data)` and send as binary frame.
   ```
3. **Implement message chunking on the client and reassembly on the server using a custom protocol (e.g., prefix each chunk with sequence number and total count).** (75% success)
   ```
   Implement message chunking on the client and reassembly on the server using a custom protocol (e.g., prefix each chunk with sequence number and total count).
   ```

## Dead Ends

- **** — The server may not support fragmentation or may reject partial messages if not properly reassembled. (70% fail)
- **** — TCP buffer size is unrelated to application-level WebSocket message limits. (90% fail)
- **** — The limit is typically server-configured, not library-specific; switching libraries rarely helps. (60% fail)