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

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

## Root Cause

The WebSocket message payload exceeds the maximum allowed frame size (default 65535 bytes) on the server or proxy.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| ws 8.16.0 | active | — | — |
| nginx 1.24.0 | active | — | — |
| AWS ALB 2.0 | active | — | — |

## Workarounds

1. **Fragment the large message into smaller chunks on the client and reassemble on the server: In JavaScript, split payload into 32KB chunks and send each with a sequence number; on the server (Node.js), buffer chunks until all received.** (90% success)
   ```
   Fragment the large message into smaller chunks on the client and reassemble on the server: In JavaScript, split payload into 32KB chunks and send each with a sequence number; on the server (Node.js), buffer chunks until all received.
   ```
2. **Increase the server's max frame size: In nginx, set `proxy_read_timeout 300s;` and `proxy_buffers 8 32k;` but more importantly configure `proxy_http_version 1.1;` and ensure the WebSocket library (e.g., ws in Node.js) sets `maxPayload: 256 * 1024`.** (85% success)
   ```
   Increase the server's max frame size: In nginx, set `proxy_read_timeout 300s;` and `proxy_buffers 8 32k;` but more importantly configure `proxy_http_version 1.1;` and ensure the WebSocket library (e.g., ws in Node.js) sets `maxPayload: 256 * 1024`.
   ```
3. **Use a message queue (e.g., Redis Pub/Sub) to offload large payloads and send only references via WebSocket.** (80% success)
   ```
   Use a message queue (e.g., Redis Pub/Sub) to offload large payloads and send only references via WebSocket.
   ```

## Dead Ends

- **Increase the WebSocket frame size limit on the client side only** — The limit is enforced by the server or intermediate proxy; client changes alone don't override it. (85% fail)
- **Compress the payload with gzip before sending** — WebSocket frames are already binary-safe; compression must be negotiated via extensions (permessage-deflate) at connection setup. (75% fail)
- **Switch to long-polling with HTTP POST to avoid frame limits** — Long-polling introduces latency and doesn't solve the underlying payload size issue; the same data may still hit HTTP body limits. (65% fail)