1009 api protocol_error ai_generated partial

WebSocket 关闭代码 1009：消息过大

WebSocket close code 1009: Message too large

ID: api/websocket-close-code-1009-message-too-large

其他格式: JSON · Markdown 中文 · English
78%修复率
87%置信度
1证据数
2023-11-20首次发现

版本兼容性

版本状态引入弃用备注
ws 8.16.0 (Node.js) active — — —
websockets 12.0 (Python) active — — —
Tornado 6.4.0 active — — —
Spring WebSocket 6.1.0 active — — —

根因分析

WebSocket 帧或消息大小超出服务器配置的最大有效负载大小（通常为 64KB 或 1MB），导致连接关闭。

English

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

generic

官方文档

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

解决方案

  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):`.
  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.
  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).

无效尝试

常见但无效的做法:

  1. 70% 失败

    The server may not support fragmentation or may reject partial messages if not properly reassembled.

  2. 90% 失败

    TCP buffer size is unrelated to application-level WebSocket message limits.

  3. 60% 失败

    The limit is typically server-configured, not library-specific; switching libraries rarely helps.