1009 communication protocol_error ai_generated true

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

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

Also available as: JSON · Markdown · 中文
82%Fix Rate
88%Confidence
1Evidence
2023-11-20First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
ws 8.16.0 active — — —
nginx 1.24.0 active — — —
AWS ALB 2.0 active — — —

Root Cause

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

generic

中文

WebSocket 消息负载超出服务器或代理允许的最大帧大小（默认 65535 字节）。

Official Documentation

https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent

Workarounds

  1. 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. 
    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. 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`. 
    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. 80% success Use a message queue (e.g., Redis Pub/Sub) to offload large payloads and send only references via WebSocket. 
    Use a message queue (e.g., Redis Pub/Sub) to offload large payloads and send only references via WebSocket.

中文步骤

  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.
  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`.
  3. Use a message queue (e.g., Redis Pub/Sub) to offload large payloads and send only references via WebSocket.

Dead Ends

Common approaches that don't work:

  1. Increase the WebSocket frame size limit on the client side only 85% fail

    The limit is enforced by the server or intermediate proxy; client changes alone don't override it.

  2. Compress the payload with gzip before sending 75% fail

    WebSocket frames are already binary-safe; compression must be negotiated via extensions (permessage-deflate) at connection setup.

  3. Switch to long-polling with HTTP POST to avoid frame limits 65% fail

    Long-polling introduces latency and doesn't solve the underlying payload size issue; the same data may still hit HTTP body limits.