◆Error Codes Wiki

HTTP WebSocket Upgrade Errors — 101 Switching Protocols Failures

Error1xx informational

Overview

Fix WebSocket connection failures including HTTP 101 upgrade issues, proxy WebSocket support, and common ws:// and wss:// connection errors.

Key Details

  • 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

Common Causes

  • 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://)

Steps

  1. 1Verify the server returns 101 Switching Protocols: check DevTools Network tab for the WS connection
  2. 2Configure Nginx: add proxy_set_header Upgrade $http_upgrade and proxy_set_header Connection 'upgrade'
  3. 3For Apache: enable mod_proxy_wstunnel and configure ProxyPass for ws:// or wss://
  4. 4Increase proxy idle timeout to match your WebSocket keepalive interval
  5. 5Use wss:// (WebSocket Secure) when the page is served over HTTPS
  6. 6Test with wscat or a WebSocket testing tool to isolate client vs server issues

Tags

websocketupgrade101wssreal-time

Related Items

http-101-switching-protocolsbrowser-websocket-errorshttp-proxy-errors-502-504-guide

More in 1xx Informational

http-100-continueHTTP 100 Continue — What It Means & How to Fix It
Informational
http-101-switching-protocolsHTTP 101 Switching Protocols — What It Means & How to Fix It
Informational
http-102-processingHTTP 102 Processing — What It Means & How to Fix It
Informational
http-103-early-hintsHTTP 103 Early Hints — What It Means & How to Fix It
Informational
http-100HTTP 100 Continue — What It Means
Informational
http-101HTTP 101 Switching Protocols Explained
Informational

Frequently Asked Questions

Production environments typically have reverse proxies or load balancers that need explicit WebSocket support configuration. Check Nginx/Apache config for Upgrade header forwarding.