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
npx skills add AgentWorkforce/relay --skill debugging-websocket-issues --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# 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 `WebSocket
- Overview
- When to Use
- Quick Reference
- The Multiple WebSocketServer Bug
- Problem
- Solution
- Debugging Techniques
- Raw Frame Inspection
- Key Hex Patterns
- Common Mistakes
- Verification Checklist
What does the debugging-websocket-issues skill do?
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
How do I install it?
Run `npx skills add AgentWorkforce/relay --skill debugging-websocket-issues --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From AgentWorkforce/relay, a repository with 784 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.