{
  "id": "communication/websocket-handshake-400-bad-request",
  "signature": "WebSocket handshake error: 400 Bad Request",
  "signature_zh": "WebSocket 握手错误：400 错误请求",
  "regex": "WebSocket.*handshake.*400",
  "domain": "communication",
  "category": "protocol_error",
  "subcategory": null,
  "root_cause": "The WebSocket handshake fails because the server rejects the upgrade request due to missing or invalid headers, such as a missing 'Sec-WebSocket-Key' or an unsupported 'Origin'.",
  "root_cause_type": "generic",
  "root_cause_zh": "WebSocket 握手失败，因为服务器拒绝升级请求，原因是缺少或无效的标头，例如缺少 'Sec-WebSocket-Key' 或不受支持的 'Origin'。",
  "versions": [
    {
      "version": "WebSocket (RFC 6455)",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Node.js 18",
      "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"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Disable header validation in the WebSocket client library",
      "why_fails": "Disabling the WebSocket library's built-in header validation does not fix the missing or invalid headers; the server still requires them for the upgrade.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "Switch to a different WebSocket client library (e.g., from ws to socket.io)",
      "why_fails": "Switching to a different WebSocket library without addressing the header issue just moves the problem; the new library will still fail if the headers are wrong.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "Increase the WebSocket connection timeout",
      "why_fails": "Increasing the timeout does not help because the error is immediate upon handshake, not a timeout issue.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Inspect and fix the 'Origin' header in the client request. For example, in JavaScript: `const socket = new WebSocket('wss://example.com/socket', { headers: { Origin: 'https://example.com' } });` Ensure the Origin matches the server's allowed list.",
      "success_rate": 0.8,
      "how": "Inspect and fix the 'Origin' header in the client request. For example, in JavaScript: `const socket = new WebSocket('wss://example.com/socket', { headers: { Origin: 'https://example.com' } });` Ensure the Origin matches the server's allowed list.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Add the 'Sec-WebSocket-Key' header manually if the library omits it. In Python with websockets: `import base64, os; key = base64.b64encode(os.urandom(16)).decode(); headers = {'Sec-WebSocket-Key': key}` and pass to the client.",
      "success_rate": 0.75,
      "how": "Add the 'Sec-WebSocket-Key' header manually if the library omits it. In Python with websockets: `import base64, os; key = base64.b64encode(os.urandom(16)).decode(); headers = {'Sec-WebSocket-Key': key}` and pass to the client.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Check the server-side Nginx configuration for WebSocket support: ensure `proxy_set_header Upgrade $http_upgrade;` and `proxy_set_header Connection \"upgrade\";` are present in the location block.",
      "success_rate": 0.85,
      "how": "Check the server-side Nginx configuration for WebSocket support: ensure `proxy_set_header Upgrade $http_upgrade;` and `proxy_set_header Connection \"upgrade\";` are present in the location block.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Inspect and fix the 'Origin' header in the client request. For example, in JavaScript: `const socket = new WebSocket('wss://example.com/socket', { headers: { Origin: 'https://example.com' } });` Ensure the Origin matches the server's allowed list.",
    "Add the 'Sec-WebSocket-Key' header manually if the library omits it. In Python with websockets: `import base64, os; key = base64.b64encode(os.urandom(16)).decode(); headers = {'Sec-WebSocket-Key': key}` and pass to the client.",
    "Check the server-side Nginx configuration for WebSocket support: ensure `proxy_set_header Upgrade $http_upgrade;` and `proxy_set_header Connection \"upgrade\";` are present in the location block."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://developer.mozilla.org/en-US/docs/Web/API/WebSocket",
  "official_doc_section": null,
  "error_code": "400",
  "verification_tier": "ai_generated",
  "confidence": 0.87,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2023-03-10",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}