# WebSocket close frame received with status code 1009 (message too big)

- **ID:** `communication/websocket-1009-frame-too-large`
- **Domain:** communication
- **Category:** protocol_error
- **Error Code:** `1009`
- **Verification:** ai_generated
- **Fix Rate:** 85%

## Root Cause

WebSocket frame or message payload exceeds the maximum allowed size configured on the server or intermediary proxy, typically 1 MB default in many implementations.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Node.js ws 8.14 | active | — | — |
| Python websockets 12.0 | active | — | — |
| Nginx 1.24 | active | — | — |
| AWS ALB | active | — | — |
| Go gorilla/websocket 1.5 | active | — | — |

## Workarounds

1. **Increase the max message size on the server, e.g., in Node.js ws: `const wss = new WebSocket.Server({ maxPayload: 10 * 1024 * 1024 });` to allow 10 MB payloads.** (95% success)
   ```
   Increase the max message size on the server, e.g., in Node.js ws: `const wss = new WebSocket.Server({ maxPayload: 10 * 1024 * 1024 });` to allow 10 MB payloads.
   ```
2. **Split large messages into multiple smaller frames and reassemble on the receiver, e.g., send chunks of 512 KB each with sequence numbers.** (85% success)
   ```
   Split large messages into multiple smaller frames and reassemble on the receiver, e.g., send chunks of 512 KB each with sequence numbers.
   ```
3. **Configure Nginx to allow larger WebSocket frames: add `proxy_read_timeout 300s; proxy_send_timeout 300s;` and ensure `client_max_body_size` is increased if behind a reverse proxy.** (80% success)
   ```
   Configure Nginx to allow larger WebSocket frames: add `proxy_read_timeout 300s; proxy_send_timeout 300s;` and ensure `client_max_body_size` is increased if behind a reverse proxy.
   ```

## Dead Ends

- **Ignore the close frame and force reconnect immediately** — The underlying message size issue persists; reconnection will trigger the same error. (85% fail)
- **Compress the entire message payload using gzip but send as a single frame** — If the compressed payload still exceeds the limit, the error persists; also, compression may not be supported by all WebSocket libraries. (60% fail)
- **Increase the WebSocket frame size limit on the client side only** — The server or proxy enforces the limit; client-side change alone does not resolve the issue. (90% fail)