1009 communication protocol_error ai_generated true

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

ID: communication/websocket-1009-frame-too-large

Also available as: JSON · Markdown · 中文
85%Fix Rate
87%Confidence
1Evidence
2024-01-12First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
Node.js ws 8.14 active — — —
Python websockets 12.0 active — — —
Nginx 1.24 active — — —
AWS ALB active — — —
Go gorilla/websocket 1.5 active — — —

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.

generic

中文

WebSocket 帧或消息负载超过服务器或中间代理配置的最大允许大小，许多实现中默认为 1 MB。

Official Documentation

https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1

Workarounds

  1. 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. 
    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. 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. 
    Split large messages into multiple smaller frames and reassemble on the receiver, e.g., send chunks of 512 KB each with sequence numbers.
  3. 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. 
    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.

中文步骤

  1. 在服务器端增加最大消息大小，例如在 Node.js ws 中：`const wss = new WebSocket.Server({ maxPayload: 10 * 1024 * 1024 });` 允许 10 MB 负载。
  2. 将大消息拆分为多个小帧并在接收端重组，例如发送每个 512 KB 的块并附带序列号。
  3. 配置 Nginx 允许更大的 WebSocket 帧：添加 `proxy_read_timeout 300s; proxy_send_timeout 300s;`，如果位于反向代理后，确保增加 `client_max_body_size`。

Dead Ends

Common approaches that don't work:

  1. Ignore the close frame and force reconnect immediately 85% fail

    The underlying message size issue persists; reconnection will trigger the same error.

  2. Compress the entire message payload using gzip but send as a single frame 60% fail

    If the compressed payload still exceeds the limit, the error persists; also, compression may not be supported by all WebSocket libraries.

  3. Increase the WebSocket frame size limit on the client side only 90% fail

    The server or proxy enforces the limit; client-side change alone does not resolve the issue.