debugging-websocket-issues

Name: debugging-websocket-issues
Author: AgentWorkforce

769stars58forks

How to install debugging-websocket-issues?

agentworkforce/relay/debugging-websocket-issues

$npx -y skills add AgentWorkforce/relay --skill debugging-websocket-issues

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Debugging WebSocket Issues
2
3	## Overview
4
5	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.
6
7	## When to Use
8
9	- Error: `Invalid WebSocket frame: RSV1 must be clear`
10	- Error: `WS_ERR_UNEXPECTED_RSV_1`
11	- Error: `Invalid frame header`
12	- WebSocket connects then immediately disconnects with code 1006
13	- Server logs success but client receives garbage data
14
15	## Quick Reference
16
17	\| Symptom \| Likely Cause \| Fix \|
18	\| ---------------------------- \| --------------------------------------------------- \| -------------------------------------- \|
19	\| RSV1 must be clear \| Multiple WSS on same server OR compression mismatch \| Use `noServer: true` mode \|
20	\| Hex starts with `48545450` \| Raw HTTP on WebSocket (0x48='H') \| Check for conflicting upgrade handlers \|
21	\| Code 1006, no reason \| Abnormal closure, often server-side abort \| Check `abortHandshake` calls \|
22	\| Works isolated, fails in app \| Something else writing to socket \| Audit all upgrade listeners \|
23
24	## The Multiple WebSocketServer Bug
25
26	### Problem
27
28	When attaching multiple `WebSocketServer` instances to the same HTTP server using the `server` option:
29
30	```typescript
31	// ❌ BAD - Both servers add upgrade listeners, causing conflicts
32	const wss1 = new WebSocketServer({ server, path: '/ws' });
33	const wss2 = new WebSocketServer({ server, path: '/ws/other' });
34	```
35
36	What happens:
37
38	1. Client connects to `/ws`
39	2. BOTH upgrade handlers fire (Node.js EventEmitter calls all listeners)
40	3. `wss1` matches path, handles upgrade successfully
41	4. `wss2` doesn't match, calls `abortHandshake(socket, 400)`
42	5. Raw `HTTP/1.1 400 Bad Request` written to the now-WebSocket socket
43	6. Client receives HTTP text as WebSocket frame data
44	7. First byte `0x48` ('H') interpreted as: RSV1=1, opcode=8 → invalid frame
45
46	### Solution
47
48	Use `noServer: true` and manually route upgrades:
49
50	```typescript
51	// ✅ GOOD - Single upgrade handler routes to correct server
52	const wss1 = new WebSocketServer({ noServer: true, perMessageDeflate: false });
53	const wss2 = new WebSocketServer({ noServer: true, perMessageDeflate: false });
54
55	server.on('upgrade', (request, socket, head) => {
56	const pathname = new URL(request.url \|\| '', `http://${request.headers.host}`).pathname;
57
58	if (pathname === '/ws') {
59	wss1.handleUpgrade(request, socket, head, (ws) => {
60	wss1.emit('connection', ws, request);
61	});
62	} else if (pathname === '/ws/other') {
63	wss2.handleUpgrade(request, socket, head, (ws) => {
64	wss2.emit('connection', ws, request);
65	});
66	} else {
67	socket.destroy();
68	}
69	});
70	```
71
72	## Debugging Techniques
73
74	### Raw Frame Inspection
75
76	Hook into the socket to see actual bytes received:
77
78	```typescript
79	ws.on('open', () => {
80	const socket = ws._socket;
81	const originalPush = socket.push.bind(socket);
82
83	socket.push = function (chunk, encoding) {
84	if (chunk) {
85	console.log('First 20 bytes (hex):', chunk.slice(0, 20).toString('hex'));
86	const byte0 = chunk[0];
87	console.log(`FIN: ${!!(byte0 & 0x80)}, RSV1: ${!!(byte0 & 0x40)}, Opcode: ${byte0 & 0x0f}`);
88
89	// Check if it's actually HTTP text
90	if (chunk.slice(0, 4).toString() === 'HTTP') {
91	console.log('* RECEIVED RAW HTTP ON WEBSOCKET *');
92	}
93	}
94	return originalPush(chunk, encoding);
95	};
96	});
97	```
98
99	### Key Hex Patterns
100
101	- `81` = FIN + text frame (normal)
102	- `82` = FIN + binary frame (normal)
103	- `88` = FIN + close frame (normal)
104	- `48545450` = "HTTP" - raw HTTP on WebSocket (bug!)
105	- `c1` or similar with bit 6 set = compressed frame (RSV1=1)
106
107	## Common Mistakes
108
109	\| Mistake \| Result \| Fix \|
110	\| ----------------------------------------------- \| ---------------------------- \| ----------------------------------------- \|
111	\| Multiple WSS with `server` option \| HTTP 400 written to socket \| Use `noServer: true` \|
112	\| `perMessageDeflate: true` (default in older ws) \| RSV1 set on frames \| Explicitly set `perMessageDeflate: false` \|
113	\| Not checking upgrade headers \| Miss compression negotiation \| Log `sec-websocket-extensions` header \|
114	\| Assuming RSV1 error = compression \| Could be raw HTTP \| Check if bytes decode as ASCII "HTTP" \|
115
116	## Verification Checklist
117
118	After fixing, verify:
119
120	- [ ] `RS

People who liked this also viewed

6 picks

Type

debugging-websocket-issues

769stars58forks

View on GitHub

How to install debugging-websocket-issues?

agentworkforce/relay/debugging-websocket-issues

$npx -y skills add AgentWorkforce/relay --skill debugging-websocket-issues

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Debugging WebSocket Issues
2
3	## Overview
4
5	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.
6
7	## When to Use
8
9	- Error: `Invalid WebSocket frame: RSV1 must be clear`
10	- Error: `WS_ERR_UNEXPECTED_RSV_1`
11	- Error: `Invalid frame header`
12	- WebSocket connects then immediately disconnects with code 1006
13	- Server logs success but client receives garbage data
14
15	## Quick Reference
16
17	\| Symptom \| Likely Cause \| Fix \|
18	\| ---------------------------- \| --------------------------------------------------- \| -------------------------------------- \|
19	\| RSV1 must be clear \| Multiple WSS on same server OR compression mismatch \| Use `noServer: true` mode \|
20	\| Hex starts with `48545450` \| Raw HTTP on WebSocket (0x48='H') \| Check for conflicting upgrade handlers \|
21	\| Code 1006, no reason \| Abnormal closure, often server-side abort \| Check `abortHandshake` calls \|
22	\| Works isolated, fails in app \| Something else writing to socket \| Audit all upgrade listeners \|
23
24	## The Multiple WebSocketServer Bug
25
26	### Problem
27
28	When attaching multiple `WebSocketServer` instances to the same HTTP server using the `server` option:
29
30	```typescript
31	// ❌ BAD - Both servers add upgrade listeners, causing conflicts
32	const wss1 = new WebSocketServer({ server, path: '/ws' });
33	const wss2 = new WebSocketServer({ server, path: '/ws/other' });
34	```
35
36	What happens:
37
38	1. Client connects to `/ws`
39	2. BOTH upgrade handlers fire (Node.js EventEmitter calls all listeners)
40	3. `wss1` matches path, handles upgrade successfully
41	4. `wss2` doesn't match, calls `abortHandshake(socket, 400)`
42	5. Raw `HTTP/1.1 400 Bad Request` written to the now-WebSocket socket
43	6. Client receives HTTP text as WebSocket frame data
44	7. First byte `0x48` ('H') interpreted as: RSV1=1, opcode=8 → invalid frame
45
46	### Solution
47
48	Use `noServer: true` and manually route upgrades:
49
50	```typescript
51	// ✅ GOOD - Single upgrade handler routes to correct server
52	const wss1 = new WebSocketServer({ noServer: true, perMessageDeflate: false });
53	const wss2 = new WebSocketServer({ noServer: true, perMessageDeflate: false });
54
55	server.on('upgrade', (request, socket, head) => {
56	const pathname = new URL(request.url \|\| '', `http://${request.headers.host}`).pathname;
57
58	if (pathname === '/ws') {
59	wss1.handleUpgrade(request, socket, head, (ws) => {
60	wss1.emit('connection', ws, request);
61	});
62	} else if (pathname === '/ws/other') {
63	wss2.handleUpgrade(request, socket, head, (ws) => {
64	wss2.emit('connection', ws, request);
65	});
66	} else {
67	socket.destroy();
68	}
69	});
70	```
71
72	## Debugging Techniques
73
74	### Raw Frame Inspection
75
76	Hook into the socket to see actual bytes received:
77
78	```typescript
79	ws.on('open', () => {
80	const socket = ws._socket;
81	const originalPush = socket.push.bind(socket);
82
83	socket.push = function (chunk, encoding) {
84	if (chunk) {
85	console.log('First 20 bytes (hex):', chunk.slice(0, 20).toString('hex'));
86	const byte0 = chunk[0];
87	console.log(`FIN: ${!!(byte0 & 0x80)}, RSV1: ${!!(byte0 & 0x40)}, Opcode: ${byte0 & 0x0f}`);
88
89	// Check if it's actually HTTP text
90	if (chunk.slice(0, 4).toString() === 'HTTP') {
91	console.log('* RECEIVED RAW HTTP ON WEBSOCKET *');
92	}
93	}
94	return originalPush(chunk, encoding);
95	};
96	});
97	```
98
99	### Key Hex Patterns
100
101	- `81` = FIN + text frame (normal)
102	- `82` = FIN + binary frame (normal)
103	- `88` = FIN + close frame (normal)
104	- `48545450` = "HTTP" - raw HTTP on WebSocket (bug!)
105	- `c1` or similar with bit 6 set = compressed frame (RSV1=1)
106
107	## Common Mistakes
108
109	\| Mistake \| Result \| Fix \|
110	\| ----------------------------------------------- \| ---------------------------- \| ----------------------------------------- \|
111	\| Multiple WSS with `server` option \| HTTP 400 written to socket \| Use `noServer: true` \|
112	\| `perMessageDeflate: true` (default in older ws) \| RSV1 set on frames \| Explicitly set `perMessageDeflate: false` \|
113	\| Not checking upgrade headers \| Miss compression negotiation \| Log `sec-websocket-extensions` header \|
114	\| Assuming RSV1 error = compression \| Could be raw HTTP \| Check if bytes decode as ASCII "HTTP" \|
115
116	## Verification Checklist
117
118	After fixing, verify:
119
120	- [ ] `RS

People who liked this also viewed

6 picks

Type