Convention: What is the correct debugging methodology when WebSocket con...

Documentation for Sessions

📏 Convention: What is the correct debugging methodology when WebSocket con...

Date: 2026-02-06
Time: 21:03:27 UTC
Session: editor2-97.11
Agent: backend
Confidence: 100%
Status: ✅ Documented

📋 Decision Context

Question:

What is the correct debugging methodology when WebSocket connections return unexpected HTTP errors?

Task: WebSocket debugging methodology

🎯 Decision Made

Chosen:

Check application code then network-level with curl/lsof

Options Considered:

  1. Only check application code
  2. Check application code then network-level with curl/lsof
  3. Just restart the server

💭 Reasoning

Step 1: Verify the application-level WebSocket routing (handlers, paths, upgrade listeners). Step 2: If the error persists, use curl -v --include --no-buffer -H 'Connection: Upgrade' -H 'Upgrade: websocket' http://localhost:PORT/path to see the raw HTTP response. Step 3: Use lsof -i :PORT to check ALL processes bound to the port — the inspector, proxy, or another process may be intercepting traffic. Step 4: Check which network interface each process binds to (127.0.0.1 vs 0.0.0.0 vs ::1) — IPv6 loopback can intercept traffic intended for IPv4. In our case, curl revealed 'WebSockets request was expected' (debugger response, not engine.io), and lsof showed the inspector had bound to loopback before the app.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation