101 Switching Protocols
The server understands and is willing to comply with the client's request to switch protocols.
Usually happens because:
- ☑ Client requests WebSockets handshakes using Connection
- ☑ HTTP/1.1 cleartext connection upgraded to
🔍 Quick Checklist:
Meaning
The HTTP 101 Switching Protocols status code indicates that the server understands the client's Upgrade request headers and agrees to switch to the protocol requested, such as upgrading HTTP/1.1 to WebSockets.
Root Causes
- Client requests WebSockets handshakes using Connection: Upgrade and Upgrade: websocket headers.
- HTTP/1.1 cleartext connection upgraded to HTTP/2.
| Cause | Frequency |
|---|---|
| Client requests WebSockets handshakes using Connection | ⭐⭐⭐⭐⭐ |
| HTTP/1.1 cleartext connection upgraded to | ⭐⭐⭐⭐ |
Common Mistakes
- Configuring reverse proxies without Upgrade headers, resulting in failed handshakes.
- Mismatch in subprotocol arguments between client and server.
How to Fix
Framework-Specific Examples
Upgrading connection to WebSocket using 'ws' package inside Express.
const WebSocket = require('ws');
const wss = new WebSocket.Server({ noServer: true });Server Configuration Examples
Configuring proxy pass-through to support Upgrade handshakes.
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";Prevention
- Always set proxy headers dynamically for HTTP upgrades.
- Verify SSL terminations correctly support wss:// protocol schemas.
Frequently Asked Questions (FAQ)
Q: Can I upgrade HTTP/2 using 101?
No. In HTTP/2, client upgrades are negotiated during ALPN handshakes over TLS, making the 101 status code obsolete for HTTP/2.
Q: What is the primary trigger of a 101 response?
It is triggered by WebSocket client connections carrying 'Upgrade: websocket' and 'Connection: Upgrade' headers.
Q: Why does my proxy return 502 Bad Gateway instead of 101?
The reverse proxy (like Nginx) is likely not configured to forward the 'Upgrade' and 'Connection' headers back to the application server.
Q: Can standard AJAX fetch handle a 101 response?
No, standard AJAX fetch requests will fail or hang. The connection must be negotiated using WebSocket or SSE APIs directly.