{
  "id": "communication/websocket-close-frame-1009-message-too-large",
  "signature": "WebSocket close frame received with status code 1009 (message too large)",
  "signature_zh": "WebSocket 关闭帧收到状态码 1009（消息过大）",
  "regex": "status code 1009|(message too large|MESSAGE_TOO_LARGE)",
  "domain": "communication",
  "category": "protocol_error",
  "subcategory": null,
  "root_cause": "The WebSocket message payload exceeds the maximum allowed frame size (default 65535 bytes) on the server or proxy.",
  "root_cause_type": "generic",
  "root_cause_zh": "WebSocket 消息负载超出服务器或代理允许的最大帧大小（默认 65535 字节）。",
  "versions": [
    {
      "version": "ws 8.16.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "nginx 1.24.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "AWS ALB 2.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Increase the WebSocket frame size limit on the client side only",
      "why_fails": "The limit is enforced by the server or intermediate proxy; client changes alone don't override it.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "Compress the payload with gzip before sending",
      "why_fails": "WebSocket frames are already binary-safe; compression must be negotiated via extensions (permessage-deflate) at connection setup.",
      "fail_rate": 0.75,
      "condition": "",
      "sources": []
    },
    {
      "action": "Switch to long-polling with HTTP POST to avoid frame limits",
      "why_fails": "Long-polling introduces latency and doesn't solve the underlying payload size issue; the same data may still hit HTTP body limits.",
      "fail_rate": 0.65,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "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.",
      "success_rate": 0.9,
      "how": "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.",
      "condition": "",
      "sources": []
    },
    {
      "action": "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`.",
      "success_rate": 0.85,
      "how": "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`.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a message queue (e.g., Redis Pub/Sub) to offload large payloads and send only references via WebSocket.",
      "success_rate": 0.8,
      "how": "Use a message queue (e.g., Redis Pub/Sub) to offload large payloads and send only references via WebSocket.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "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.",
    "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`.",
    "Use a message queue (e.g., Redis Pub/Sub) to offload large payloads and send only references via WebSocket."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent",
  "official_doc_section": null,
  "error_code": "1009",
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.82,
  "resolvable": "true",
  "first_seen": "2023-11-20",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}