Agent skill

Debugging Websocket Issues

by AgentWorkforce in AgentWorkforce/relay

A skill your agent uses when seeing WebSocket errors like "Invalid frame header", "RSV1 must be clear", or "WSERRUNEXPECTEDRSV1" - covers multiple WebSocketServer conflicts, compression issues, and…

Apache-2.0Auto-check passedBackend & APIs

Install Debugging Websocket Issues

skills CLI
$ npx skills add AgentWorkforce/relay --skill debugging-websocket-issues -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install AgentWorkforce/relay debugging-websocket-issues --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/AgentWorkforce/relay.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/debugging-websocket-issues .claude/skills/debugging-websocket-issues && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
debugging-websocket-issues
GitHub stars
865
Used in
1 other repo
Token cost
~1.3k tokens
SKILL.md length
362 words
Files
1
Skills in repo
14
Repo updated
First seen
Licence
Apache-2.0

At a glance

A skill your agent uses when seeing WebSocket errors like "Invalid frame header", "RSV1 must be clear", or "WSERRUNEXPECTEDRSV1" - covers multiple WebSocketServer conflicts, compression issues, and…

  • Works in 7 steps: Client connects to /ws → BOTH upgrade handlers fire (Node.js… → wss1 matches path, handles upgrade… → …
  • Seeing WebSocket errors like Invalid frame header
  • SKILL.md covers Overview, When to Use, Quick Reference and The Multiple WebSocketServer Bug, plus 3 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Debugging Websocket Issues is an agent skill from AgentWorkforce/relay. Use when seeing WebSocket errors like "Invalid frame header", "RSV1 must be clear", or "WSERRUNEXPECTEDRSV1" - covers multiple WebSocketServer conflicts, compression issues, and raw frame debugging techniques

Its SKILL.md is about 1.3k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Backend & APIs, covering Realtime and WebSockets and Debugging. The repository describes itself as: Infrastructure for coding agents. The licence is Apache-2.0.

When your agent uses it

  • Seeing WebSocket errors like Invalid frame header
  • RSV1 must be clear
  • WSERRUNEXPECTEDRSV1 - covers multiple WebSocketServer conflicts
  • Compression issues

Example prompts

  • “Invalid frame header”
  • “RSV1 must be clear”
  • “WSERRUNEXPECTEDRSV1”
  • “/debugging-websocket-issues”

Requirements

  • Node.js

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

  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. First byte 0x48 ('H') interpreted as: RSV1=1, opcode=8 → invalid frame

What it can do on your machine

Read from SKILL.md and the folder at commit 734600d. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are typescript).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Debugging Websocket Issues loads about 1.3k tokens when it runs. Until then it costs about 60 tokens; SKILL.md has 362 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~60
When it runs · the whole SKILL.md, loaded when a task matches
~1.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from AgentWorkforce/relay at commit 734600d, republished under its Apache-2.0 licence (© AgentWorkforce). 362 words, ~1,306 tokens.

Download SKILL.mdSave it as .claude/skills/debugging-websocket-issues/SKILL.md (or your agent's skills folder).
name
debugging-websocket-issues
description
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
tags
websocket, debugging, ws, node

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

SymptomLikely CauseFix
RSV1 must be clearMultiple WSS on same server OR compression mismatchUse noServer: true mode
Hex starts with 48545450Raw HTTP on WebSocket (0x48='H')Check for conflicting upgrade handlers
Code 1006, no reasonAbnormal closure, often server-side abortCheck abortHandshake calls
Works isolated, fails in appSomething else writing to socketAudit 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 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. First byte 0x48 ('H') interpreted as: RSV1=1, opcode=8 → invalid frame
Show full SKILL.md (148 more words)Show less
Solution

Use noServer: true and manually route upgrades:

typescript
// ✅ GOOD - Single upgrade handler routes to correct server
const wss1 = new WebSocketServer({ noServer: true, perMessageDeflate: false });
const wss2 = new WebSocketServer({ noServer: true, perMessageDeflate: false });

server.on('upgrade', (request, socket, head) => {
  const pathname = new URL(request.url || '', `http://${request.headers.host}`).pathname;

  if (pathname === '/ws') {
    wss1.handleUpgrade(request, socket, head, (ws) => {
      wss1.emit('connection', ws, request);
    });
  } else if (pathname === '/ws/other') {
    wss2.handleUpgrade(request, socket, head, (ws) => {
      wss2.emit('connection', ws, request);
    });
  } else {
    socket.destroy();
  }
});

Debugging Techniques

Raw Frame Inspection

Hook into the socket to see actual bytes received:

typescript
ws.on('open', () => {
  const socket = ws._socket;
  const originalPush = socket.push.bind(socket);

  socket.push = function (chunk, encoding) {
    if (chunk) {
      console.log('First 20 bytes (hex):', chunk.slice(0, 20).toString('hex'));
      const byte0 = chunk[0];
      console.log(`FIN: ${!!(byte0 & 0x80)}, RSV1: ${!!(byte0 & 0x40)}, Opcode: ${byte0 & 0x0f}`);

      // Check if it's actually HTTP text
      if (chunk.slice(0, 4).toString() === 'HTTP') {
        console.log('*** RECEIVED RAW HTTP ON WEBSOCKET ***');
      }
    }
    return originalPush(chunk, encoding);
  };
});
Key Hex Patterns
  • 81 = FIN + text frame (normal)
  • 82 = FIN + binary frame (normal)
  • 88 = FIN + close frame (normal)
  • 48545450 = "HTTP" - raw HTTP on WebSocket (bug!)
  • c1 or similar with bit 6 set = compressed frame (RSV1=1)

Common Mistakes

MistakeResultFix
Multiple WSS with server optionHTTP 400 written to socketUse noServer: true
perMessageDeflate: true (default in older ws)RSV1 set on framesExplicitly set perMessageDeflate: false
Not checking upgrade headersMiss compression negotiationLog sec-websocket-extensions header
Assuming RSV1 error = compressionCould be raw HTTPCheck if bytes decode as ASCII "HTTP"

Verification Checklist

After fixing, verify:

  • RSV1: false in frame inspection
  • Extensions header: NONE in upgrade response
  • No HTTP/1.1 in raw frame data
  • Messages received match sent payload size
  • Multiple broadcasts work (test interval sends)

© AgentWorkforce, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/debugging-websocket-issues of AgentWorkforce/relay.

Open the folder on GitHubat commit 734600d

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in AgentWorkforce/relay, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Debugging Websocket Issues next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Debugging Websocket Issues compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Debugging Websocket Issues this skillAgentWorkforce/relay8651 repos~1.3kAutomated safety check: PassApache-2.0
Supabase Development and Debuggingsupabase/agent-skills2.7k3 repos~3.6kAutomated safety check: PassMIT
Debug Logsadam-s/intercept189—~1.1kAutomated safety check: PassMIT
Gateway Proxy Debugvercel-labs/vercel-openclaw-archived117—~573Automated safety check: PassMIT
Realtimebutterbase-ai/butterbase-skills534—~2.1kAutomated safety check: PassMIT
Fullstack Devinfometa/workbuddyskills342—~1kAutomated safety check: PassMIT

Similar skills

  • Official

    General Supabase skill for database, auth, Edge Functions, Realtime and storage work, plus client libraries, migrations, security audits, debugging and reading logs.

    2.7k GitHub starsUsed in 3 repos~3.6k tokens
    Backend & APIsAuto-check passed
  • Debug Logs

    adam-s/intercept

    Iterative debugging with targeted logs. An agent skill from adam-s/intercept.

    189 GitHub stars~1.1k tokensUpdated 2 mo ago
    Backend & APIsAuto-check passed
  • Gateway Proxy Debug

    vercel-labs/vercel-openclaw-archived

    Official

    Gateway and proxy debugging for vercel-openclaw: /gateway routing, HTML injection, WebSocket rewrite, gateway-token handoff, waiting page, status heartbeat, sandbox port URL cache, and proxy auth.

    117 GitHub stars~573 tokensUpdated 4 mo ago
    Backend & APIsAuto-check passed
  • Realtime

    butterbase-ai/butterbase-skills

    A skill your agent uses when enabling WebSocket subscriptions for live database changes, presence/multiplayer state, or when debugging clients that connect but receive no events

    534 GitHub stars~2.1k tokensUpdated 2 days ago
    Backend & APIsAuto-check passed
  • Fullstack Dev

    infometa/workbuddyskills

    Full-stack backend architecture and frontend-backend integration guide.

    342 GitHub stars~1k tokensUpdated today
    Backend & APIsAuto-check passed
  • EasyEDA Pro API Bridge

    easyeda/easyeda-api-skill

    Gives an agent the EasyEDA Pro API reference and a WebSocket bridge to run code in a live EasyEDA client, for PCB, schematic and library work and extension development.

    855 GitHub stars~7.8k tokensUpdated 5 days ago
    DevelopmentAuto-check passed

More from AgentWorkforce/relay

All 14 skills in this repo
  • A skill your agent uses when testing web applications with visual verification - automates Chrome browser interactions, element selection, and screenshot capture for confirming UI functionality

    865 GitHub starsUsed in 1 repo~2.2k tokens
    Auto-check passed
  • Agent Relay

    AgentWorkforce/relay

    A skill your agent uses when you need Codex to coordinate multiple agents through Agent Relay for peer-to-peer messaging, lead/worker handoffs, or shared status tracking across sub-agents and…

    865 GitHub stars~1.7k tokensUpdated today
    Auto-check passed
  • GitHub OAuth Nango Integration

    AgentWorkforce/relay

    A skill your agent uses when implementing GitHub OAuth + GitHub App authentication with Nango - provides two-connection pattern for user login and repo access with webhook handling

    865 GitHub starsUsed in 1 repo~3.4k tokens
    Auto-check passed
  • Implementing Command Palettes

    AgentWorkforce/relay

    A skill your agent uses when building Cmd+K command palettes in React - covers keyboard navigation with arrow keys, keeping selected items in view with scrollIntoView, filtering with shortcut…

    865 GitHub starsUsed in 1 repo~2.5k tokens
    Auto-check passed
  • Using Agent Relay

    AgentWorkforce/relay

    A skill your agent uses when you are a registered relay agent (a spawned worker, or a lead that called registeragent) coordinating with peers in real time over current Agent Relay MCP tools -…

    865 GitHub starsUsed in 1 repo~2k tokens
    Auto-check passed
  • A skill your agent uses when deploying changes to staging across relay, relay-dashboard, and relay-cloud repos - coordinates multi-repo branch syncing using git worktrees, automatically triggers…

    865 GitHub stars~3.2k tokensUpdated today
    Auto-check passed

Categories

Questions about Debugging Websocket Issues

What does Debugging Websocket Issues do?

A skill your agent uses when seeing WebSocket errors like "Invalid frame header", "RSV1 must be clear", or "WSERRUNEXPECTEDRSV1" - covers multiple WebSocketServer conflicts, compression issues, and…. Debugging Websocket Issues is an agent skill from AgentWorkforce/relay.

When should I use Debugging Websocket Issues?

Debugging Websocket Issues fits situations like: seeing WebSocket errors like Invalid frame header; RSV1 must be clear; WSERRUNEXPECTEDRSV1 - covers multiple WebSocketServer conflicts; compression issues.

How do I install Debugging Websocket Issues in Claude Code?

Run `npx skills add AgentWorkforce/relay --skill debugging-websocket-issues -a claude-code`. Or copy the skill folder (.claude/skills/debugging-websocket-issues in AgentWorkforce/relay) into .claude/skills/debugging-websocket-issues in your project. Claude Code loads it when a task matches its description.

How do I install Debugging Websocket Issues in Codex?

Run `npx skills add AgentWorkforce/relay --skill debugging-websocket-issues -a codex`. Or copy the skill folder (.claude/skills/debugging-websocket-issues in AgentWorkforce/relay) into .agents/skills/debugging-websocket-issues in your project. Codex loads it when a task matches its description.

Can I use Debugging Websocket Issues in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add AgentWorkforce/relay --skill debugging-websocket-issues -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/debugging-websocket-issues, .gemini/skills/debugging-websocket-issues, .github/skills/debugging-websocket-issues and .opencode/skills/debugging-websocket-issues in your project.

What does Debugging Websocket Issues need to run?

SKILL.md names no scripts, command-line tools or credentials: Debugging Websocket Issues is instructions for the agent only. Our summary lists: Node.js.

Does Debugging Websocket Issues access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Debugging Websocket Issues safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Debugging Websocket Issues use?

Debugging Websocket Issues is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Debugging Websocket Issues use?

About 1.3k tokens (SKILL.md is roughly 5.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Debugging Websocket Issues?

Skills that share tags, products or a category with Debugging Websocket Issues: Supabase Development and Debugging (supabase/agent-skills, 2.7k stars), Debug Logs (adam-s/intercept, 189 stars), Gateway Proxy Debug (vercel-labs/vercel-openclaw-archived, 117 stars) and Realtime (butterbase-ai/butterbase-skills, 534 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Debugging Websocket Issues?

AgentWorkforce (a GitHub organization) maintains it in AgentWorkforce/relay, which has 865 GitHub stars. The repository holds 14 skills in this directory. The repository was last updated on October 7, 2026.

Source: AgentWorkforce/relay on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.