Diagnosing Socket.IO v4 Transport Fallback to Long-Polling

Recognizable Condition

Clients connect but the server logs show polling as the transport instead of websocket. Symptoms include high connection counts with frequent reconnects, increased latency on the first message, and load balancer health checks failing on WebSocket upgrade requests. In browser devtools, the Network tab shows repeated XHR requests to /socket.io/?EIO=4&transport=polling rather than a single 101 Switching Protocols response.

Cause and Diagnostic Table

Ordered Checks

1. Verify server transport logs. Start the server with DEBUG=socket.io* node server.js and confirm whether ws or polling is logged on connect.
2. Confirm proxy passes upgrade headers. In nginx, ensure the location block for Socket.IO includes:

   proxy_set_header Upgrade $http_upgrade;
   proxy_set_header Connection "upgrade";

   Reload nginx (nginx -s reload, requires root) and retest.
3. Test direct server access. Bypass the proxy with curl -i -N -H 'Connection: Upgrade' -H 'Upgrade: websocket' http://<server-host>:3000/socket.io/?EIO=4&transport=websocket. Expect HTTP 101. Run from a client machine with network access to the backend port.
4. Check client transports order. The client defaults to ['websocket', 'polling']. If code sets transports: ['polling', 'websocket'] or forceNew: true, WebSocket may never be attempted.
5. Inspect Network tab for 101 vs 200. In devtools, filter by both WS and XHR. A successful upgrade shows 101 Switching Protocols; polling shows 200 OK on repeated XHRs.
6. Review pingInterval and pingTimeout. Socket.IO v4 defaults: pingInterval: 25000, pingTimeout: 20000. If network latency spikes exceed pingTimeout, the client falls back. Consider increasing pingTimeout to 60000 for high‑latency links.

Fixes Tied to Findings

• Proxy blocking upgrade: Add the nginx headers above. For HAProxy, use option http-server-close and http-request set-header Connection Upgrade.
• Firewall blocks wss://: Enforce TLS on port 443 and ensure the firewall allows WebSocket frames. Some TLS inspection proxies break frames; if unavoidable, consider a dedicated non‑inspected port.
• Aggressive fallback: Increase pingTimeout on both server and client: new Server({ pingTimeout: 60000 }) and io({ pingTimeout: 60000 }).
• Scaling polling overhead: Deploy the Redis adapter (@socket.io/redis-adapter) and enable sticky sessions (e.g., nginx ip_hash or cookie‑based affinity) so polling requests reach the same worker.
• Client misconfiguration: Remove legacy forceNew: true and ensure transports array starts with 'websocket'.

Escalation Criteria

1. More than 20% of connections remain on polling after proxy fixes — capture packets (tcpdump/Wireshark) to see if upgrade frames are dropped.
2. Memory usage correlates with polling connection count — profile with clinic.js or node --inspect to detect leaks in the polling transport.
3. WebSocket handshake succeeds but drops within pingInterval — check TCP keepalive settings on the OS and intermediate devices.
4. Fallback spike after a deployment — verify version mismatch (v3 client vs v4 server or vice‑versa) and ensure both sides use compatible Engine.IO protocol (EIO=4 for v4).

Verification Steps

• Server debug: DEBUG=socket.io* node server.js — observe transport type on each connect.
• Client debug: In browser console, set localStorage.debug = 'socket.io-client:socket' and reload to watch transport negotiation logs.
• Load test: Use artillery.io or wsload to simulate connections and measure WebSocket vs polling percentage via custom metrics.
• Proxy error log: Check nginx error.log for upstream prematurely closed connection during upgrade attempts.

Limitations and Notes

• Socket.IO v4 changed default pingInterval/pingTimeout; configurations from v2/v3 may cause unexpected fallback.
• Redis adapter requires sticky sessions for polling; without them, session not found errors appear.
• Browser devtools WS filter hides polling XHRs; always enable both WS and XHR filters.
• Corporate TLS inspection proxies often break WebSocket frames even over wss://.
• Setting transports: ['websocket'] disables fallback entirely; the client will fail if WebSocket is blocked.
• Polling connection metrics are inflated — compare active sockets vs. HTTP request rate to gauge real load.

Practical Result Check

After applying fixes, run the curl upgrade test again and confirm HTTP 101. Then start the server with debug enabled, connect a client, and verify the log shows transport: websocket. Monitor the connection count and request rate for 10 minutes; polling should drop to near zero.