{
  "id": "api/websocket-close-code-1009-message-too-large",
  "signature": "WebSocket close code 1009: Message too large",
  "signature_zh": "WebSocket 关闭代码 1009：消息过大",
  "regex": "WebSocket\\s+close\\s+code\\s+1009:\\s+Message\\s+too\\s+large",
  "domain": "api",
  "category": "protocol_error",
  "subcategory": null,
  "root_cause": "The WebSocket frame or message size exceeds the server's configured maximum payload size, typically 64KB or 1MB, causing the connection to close.",
  "root_cause_type": "generic",
  "root_cause_zh": "WebSocket 帧或消息大小超出服务器配置的最大有效负载大小（通常为 64KB 或 1MB），导致连接关闭。",
  "versions": [
    {
      "version": "ws 8.16.0 (Node.js)",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "websockets 12.0 (Python)",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Tornado 6.4.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Spring WebSocket 6.1.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "The server may not support fragmentation or may reject partial messages if not properly reassembled.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "TCP buffer size is unrelated to application-level WebSocket message limits.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "The limit is typically server-configured, not library-specific; switching libraries rarely helps.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "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):`.",
      "success_rate": 0.9,
      "how": "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):`.",
      "condition": "",
      "sources": []
    },
    {
      "action": "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.",
      "success_rate": 0.85,
      "how": "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.",
      "condition": "",
      "sources": []
    },
    {
      "action": "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).",
      "success_rate": 0.75,
      "how": "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).",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "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):`.",
    "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.",
    "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)."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent#status_codes",
  "official_doc_section": null,
  "error_code": "1009",
  "verification_tier": "ai_generated",
  "confidence": 0.87,
  "fix_success_rate": 0.78,
  "resolvable": "partial",
  "first_seen": "2023-11-20",
  "last_confirmed": "2024-06-01",
  "last_updated": "2025-03-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}