{
  "id": "communication/websocket-1009-frame-too-large",
  "signature": "WebSocket close frame received with status code 1009 (message too big)",
  "signature_zh": "WebSocket 关闭帧接收，状态码 1009（消息过大）",
  "regex": "WebSocket.*close.*1009|message too big|frame too large",
  "domain": "communication",
  "category": "protocol_error",
  "subcategory": null,
  "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.",
  "root_cause_type": "generic",
  "root_cause_zh": "WebSocket 帧或消息负载超过服务器或中间代理配置的最大允许大小，许多实现中默认为 1 MB。",
  "versions": [
    {
      "version": "Node.js ws 8.14",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Python websockets 12.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Nginx 1.24",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "AWS ALB",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Go gorilla/websocket 1.5",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Ignore the close frame and force reconnect immediately",
      "why_fails": "The underlying message size issue persists; reconnection will trigger the same error.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "Compress the entire message payload using gzip but send as a single frame",
      "why_fails": "If the compressed payload still exceeds the limit, the error persists; also, compression may not be supported by all WebSocket libraries.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    },
    {
      "action": "Increase the WebSocket frame size limit on the client side only",
      "why_fails": "The server or proxy enforces the limit; client-side change alone does not resolve the issue.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "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.",
      "success_rate": 0.95,
      "how": "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.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Split large messages into multiple smaller frames and reassemble on the receiver, e.g., send chunks of 512 KB each with sequence numbers.",
      "success_rate": 0.85,
      "how": "Split large messages into multiple smaller frames and reassemble on the receiver, e.g., send chunks of 512 KB each with sequence numbers.",
      "condition": "",
      "sources": []
    },
    {
      "action": "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.",
      "success_rate": 0.8,
      "how": "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.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "在服务器端增加最大消息大小，例如在 Node.js ws 中：`const wss = new WebSocket.Server({ maxPayload: 10 * 1024 * 1024 });` 允许 10 MB 负载。",
    "将大消息拆分为多个小帧并在接收端重组，例如发送每个 512 KB 的块并附带序列号。",
    "配置 Nginx 允许更大的 WebSocket 帧：添加 `proxy_read_timeout 300s; proxy_send_timeout 300s;`，如果位于反向代理后，确保增加 `client_max_body_size`。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1",
  "official_doc_section": null,
  "error_code": "1009",
  "verification_tier": "ai_generated",
  "confidence": 0.87,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2024-01-12",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}