HTTP WebSocket Upgrade Errors — 101 Switching Protocols Failures

Fix WebSocket connection failures including HTTP 101 upgrade issues, proxy WebSocket support, and common ws:// and wss:// connection errors. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.

Here are the key things to understand: WebSocket connections start with an HTTP/1.1 Upgrade request and expect a 101 Switching Protocols response. The client sends Upgrade: websocket and Connection: Upgrade headers. If the server responds with anything other than 101, the WebSocket connection fails. Common failure modes: proxy dropping Upgrade headers, server not supporting WebSocket, TLS issues with wss://. WebSocket connections are long-lived, which can conflict with proxy/load balancer idle timeouts. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: Reverse proxy (Nginx, Apache) not configured to forward WebSocket Upgrade headers. Load balancer terminating the connection before the upgrade completes. Server application not handling the WebSocket upgrade handshake. Firewall blocking WebSocket connections on non-standard ports. Mixed content: attempting ws:// from an HTTPS page (must use wss://). Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Verify the server returns 101 Switching Protocols: check DevTools Network tab for the WS connection. Configure Nginx: add proxy_set_header Upgrade $http_upgrade and proxy_set_header Connection 'upgrade'. For Apache: enable mod_proxy_wstunnel and configure ProxyPass for ws:// or wss://. Increase proxy idle timeout to match your WebSocket keepalive interval. Use wss:// (WebSocket Secure) when the page is served over HTTPS. Test with wscat or a WebSocket testing tool to isolate client vs server issues. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.

This article is part of our HTTP Status Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.