debugging-websocket-issueslisted

# 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: `WS_ERR_UNEXPECTED_RSV_1` - 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: ```typescript // ❌ BAD - Both servers add upgrade listeners, causing conflicts const wss1 = new WebSocketServer({ server, path: '/ws' }); const wss2 = new WebSocketServer({ server, path: '/ws/other' }); ``` **What happens:** 1. Client connects to `/ws` 2. BOTH upgrade handlers fire (Node.js EventEmitter calls all