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.

GitHub stars: 719
last updated: Jun 11, 2026

View on GitHub

Install

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

Installs into .claude/skills of the current project.

Files

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.