Debugging Websocket Issues

The Multiple WebSocketServer Bug

Problem

When attaching multiple WebSocketServer instances to the same HTTP server using the server option:

// ❌ 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

Solution

Use noServer: true and manually route upgrades:

// ✅ 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:

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

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)