101 Status Code: Switching Protocols Explained

What does the 101 status code mean?

The HTTP 101 status code means the server accepted a client’s request to change protocols and is switching the existing connection to the requested protocol. A 101 Switching Protocols response is successful only if the response names the expected protocol and the connection then follows that protocol.

A protocol is a set of rules that a client and server use to communicate. Unlike a normal HTTP response that delivers a page or data and completes the exchange, a 101 response code marks a transition on the same connection.

The 101 HTTP response is informational rather than page content. Seeing status code 101 is therefore not automatically an error. The important question is whether the client and server continued communicating correctly after the switch.

When does HTTP 101 Switching Protocols appear?

HTTP 101 Switching Protocols appears when a client asks a server to upgrade an HTTP connection to another protocol and the server agrees. The most common example is a WebSocket connection, which supports ongoing two-way communication between a browser and a server.

A WebSocket handshake begins as an HTTP request. If the server accepts it, the server returns the HTTP status code 101 and the connection changes from HTTP message exchange to WebSocket frames. Applications may use this kind of persistent connection for live updates, messaging, dashboards, or other features that need data to move in either direction without a new request each time.

The 101 response can also appear with another supported protocol upgrade. In every case, the specific protocol named in the request and response matters more than the presence of 101 alone.

How does an HTTP protocol upgrade work?

An upgrade header is an HTTP header that identifies the protocol a client wants to use next. At a practical level, a successful protocol change follows this sequence:

1. The client opens an HTTP connection and sends a request containing an Upgrade header with the desired protocol.
2. The request includes a Connection header indicating that the Upgrade header applies to this connection.
3. The server checks whether the requested protocol is supported and whether the request contains any protocol-specific information it requires.
4. If the server accepts the change, it sends a 101 Switching Protocols response. The response headers identify the selected protocol and confirm the connection upgrade.
5. After the response headers, both sides stop treating the connection as an ordinary HTTP exchange and begin using the selected protocol.

For WebSocket connections, the handshake includes additional WebSocket headers that let the client verify the server’s response. A 101 status code without the required matching headers does not establish a valid WebSocket connection.

How can you check a 101 response?

To check an HTTP 101 status code, inspect both the handshake and what happens after it. A correct status line is necessary, but continuing traffic is the clearest sign that the switch worked.

1. Open the browser’s developer tools and select the Network panel before reproducing the problem.
2. Find the connection request. WebSocket requests may appear under a separate WS filter.
3. Inspect the request headers. Confirm that the Upgrade and Connection headers are present and name the intended protocol.
4. Inspect the response. Confirm that it reports status code 101 and that its Upgrade header matches the requested protocol.
5. For WebSocket traffic, open the Messages or Frames view. Messages appearing after the handshake show that the upgraded connection is active.
6. Check the browser console and application logs for handshake errors, immediate disconnects, or protocol parsing failures.

Command-line diagnostics can also display request and response headers. Use a tool that supports the protocol being tested; a basic HTTP request may show the handshake but may not continue speaking the upgraded protocol. Server access logs can confirm whether the request reached the intended service, while proxy logs can show whether an intermediary changed or rejected it.

Why can a 101 protocol upgrade fail?

A protocol upgrade can fail before the server sends a 101 response or immediately afterward. Common causes include:

• Missing headers: The client omits the Upgrade header, the Connection header, or required protocol-specific fields.
• Incorrect values: Header names may be accepted without regard to letter case, but header values, tokens, versions, and protocol-specific verification data still must be valid.
• Unsupported protocol: The server does not recognize or allow the requested upgrade or version.
• Proxy interference: A reverse proxy, gateway, firewall, or load balancer removes upgrade headers, does not forward the persistent connection, or closes it early.
• TLS problems: A secure connection fails because of certificate, hostname, trust, or encryption negotiation issues before the HTTP upgrade can complete.
• Server configuration: The upgrade route points to the wrong service, protocol handling is disabled, or the application is not listening where the proxy expects it.
• Post-upgrade failure: The server returns a valid 101 response, but either side sends invalid frames, rejects authentication, times out, or closes the connection.

How do you troubleshoot an HTTP 101 response?

Troubleshoot the 101 response code in connection order so you can identify where the handshake stops:

1. Check the client request. Verify the destination, request method, Upgrade and Connection headers, requested protocol version, and any required authentication or protocol-specific headers.
2. Check the server response. Confirm that the response is actually HTTP 101 Switching Protocols and that the selected protocol and handshake values match what the client requested.
3. Check the connection transition. Look for frames, messages, or other protocol traffic after the response. Note whether the connection stays open or closes immediately.
4. Test each intermediary. Review reverse-proxy, gateway, firewall, and load-balancer settings for upgrade support, header forwarding, connection reuse, and timeout behavior.
5. Check TLS separately. If the connection is encrypted, resolve certificate or negotiation errors before investigating the HTTP upgrade.
6. Compare timestamps in logs. Match the client attempt with proxy and application entries to find the component that rejected, changed, or ended the connection.
7. Retest after one change. Reproduce the same request and confirm both the 101 response and ongoing protocol traffic.

If the server returns 101 but no upgraded traffic follows, focus on handshake validation, proxy behavior, and application logs. If no HTTP 101 status code appears, begin with the outgoing request and trace it through each intermediary to the server.