Agent skill · software engineering · aiskillstore
debugging-websocket-issues
Use when seeing WebSocket errors like "Invalid frame header", "RSV1 must be clear", or "WS_ERR_UNEXPECTED_RSV_1" - covers multiple WebSocketServer conflicts, compression issues, and raw frame debugging techniques
Why this skill is useful
Provides specific debugging techniques and patterns for WebSocket issues that the AI wouldn't reliably generate on its own.
What it needs
About 3k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
Debugging WebSocket Issues Overview WebSocket "invalid frame header" errors often stem from raw HTTP being written to an upgraded socket, not actual frame corruption. The most common cause is multiple WebSocketServer instances conflicting on the same HTTP server. When to Use Error: Invalid WebSocket frame: RSV1 must be clear Error: WSERRUNEXPECTEDRSV1 Error: Invalid frame header WebSocket connects then immediately disconnects with code 1006 Server logs success but client receives garbage data Quick Reference Symptom Likely Cause Fix ---------------------------- --------------------------------------------------- -------------------------------------- RSV1 must be clear Multiple WSS on same server OR compression mismatch Use noServer: true mode Hex starts with 48545450 Raw HTTP on WebSocket (0x48='H') Check for conflicting upgrade handlers Code 1006, no reason Abnormal closure, often server-side abort Check abortHandshake calls Works isolated, fails in app Something else writing to socket Audit all upgrade listeners The Multiple WebSocketServer Bug Problem When attaching multiple WebSocketServer instances to the same HTTP server using the server option: What happens: 1. Client connects to /ws 2. BOTH upgrade handlers fire (Node.js EventEmitter calls all listeners) 3. wss1 matches path, handles upgrade successfully 4. wss2 doesn't match, calls abortHandshake(socket, 400) 5. Raw HTTP/1.1 400 Bad Request written to the now-WebSocket socket 6. Client receives HTTP text as WebSocket frame data 7. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/debugging-websocket-issues