1002 api protocol_error ai_generated true

WebSocket close code 1002: Protocol Error

ID: api/websocket-close-code-1002-protocol-error

Also available as: JSON · Markdown · 中文
80%Fix Rate
85%Confidence
1Evidence
2023-09-05First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
RFC 6455 active — — —
ws library 8.x active — — —
Socket.IO 4.x active — — —
Spring WebSocket 6.0 active — — —
Node.js ws 8.14+ active — — —

Root Cause

WebSocket frame was malformed or contained invalid data, such as a reserved opcode or fragmented control frame.

generic

中文

WebSocket 帧格式错误或包含无效数据，例如保留操作码或分片控制帧。

Official Documentation

https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1

Workarounds

  1. 90% success Validate that control frames (e.g., ping, pong, close) are not fragmented. In JavaScript, ensure you are not sending a fragmented ping frame: // Bad: Sending a fragmented ping ws.send(Buffer.from('ping'), { fin: false, opcode: 0x9 }); // Wrong! // Good: Send a complete ping frame ws.ping(); // Uses correct non-fragmented frame 
    Validate that control frames (e.g., ping, pong, close) are not fragmented. In JavaScript, ensure you are not sending a fragmented ping frame:
// Bad: Sending a fragmented ping
ws.send(Buffer.from('ping'), { fin: false, opcode: 0x9 }); // Wrong!
// Good: Send a complete ping frame
ws.ping(); // Uses correct non-fragmented frame
  2. 85% success Check for reserved opcodes (0x3-0x7, 0xB-0xF) in the frame. If using a custom WebSocket library, ensure opcode is in {0x0, 0x1, 0x2, 0x8, 0x9, 0xA}. 
    Check for reserved opcodes (0x3-0x7, 0xB-0xF) in the frame. If using a custom WebSocket library, ensure opcode is in {0x0, 0x1, 0x2, 0x8, 0x9, 0xA}.

中文步骤

  1. Validate that control frames (e.g., ping, pong, close) are not fragmented. In JavaScript, ensure you are not sending a fragmented ping frame:
// Bad: Sending a fragmented ping
ws.send(Buffer.from('ping'), { fin: false, opcode: 0x9 }); // Wrong!
// Good: Send a complete ping frame
ws.ping(); // Uses correct non-fragmented frame
  2. Check for reserved opcodes (0x3-0x7, 0xB-0xF) in the frame. If using a custom WebSocket library, ensure opcode is in {0x0, 0x1, 0x2, 0x8, 0x9, 0xA}.

Dead Ends

Common approaches that don't work:

  1. 90% fail

    The error is immediate and not related to timeouts.

  2. 80% fail

    The root cause is in the client's frame construction, not server state.