Debugging Websocket Issues

If you've ever seen "RSV1 must be clear" or "Invalid frame header" errors and wondered why your WebSocket is receiving HTTP garbage, this walks you through the actual culprit: multiple WebSocketServer instances on the same HTTP server. Each adds an upgrade listener, so one handles the connection while another simultaneously writes "HTTP/1.1 400" to the now-upgraded socket. The guide covers the noServer pattern to fix it, raw frame inspection techniques to see what's actually hitting the wire, and a hex lookup table for identifying whether you're dealing with compression flags or literal "HTTP" bytes being parsed as frames. Solid reference when WebSockets work in isolation but explode in production.

Install to Claude Code

npx -y skills add agentworkforce/relay --skill debugging-websocket-issues --agent claude-code