# Debugging Websocket Issues

Use when seeing WebSocket errors like "Invalid frame header", "RSV1 must be clear", or...

- Repository: https://github.com/AgentWorkforce/relay (1088 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add AgentWorkforce/relay --skill debugging-websocket-issues -g -a claude-code -y`
Codex: `npx skills add AgentWorkforce/relay --skill debugging-websocket-issues -g -a codex -y`
Cursor: `npx skills add AgentWorkforce/relay --skill debugging-websocket-issues -g -a cursor -y`
Gemini CLI: `npx skills add AgentWorkforce/relay --skill debugging-websocket-issues -g -a gemini-cli -y`

## 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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:**

The rest: https://github.com/AgentWorkforce/relay/blob/HEAD/.claude/skills/debugging-websocket-issues/SKILL.md