Upgrade general both

What it does

Upgrade lets the client request that the server switch to a different protocol on the same TCP connection. The most common use is upgrading an HTTP/1.1 connection to a WebSocket connection — but the mechanism applies to any protocol switch.

The request starts as a normal HTTP request; if the server agrees to the upgrade, it responds with 101 Switching Protocols and the connection transitions to the new protocol.

Syntax

Upgrade: <protocol>[/<version>]

Always paired with Connection: Upgrade — Upgrade is a hop-by-hop header and must be listed in Connection so proxies know to strip it rather than forward it:

Upgrade: websocket
Upgrade: HTTP/2.0
Upgrade: websocket, HTTP/2.0

The WebSocket handshake

WebSockets are the primary real-world use of Upgrade. The full handshake:

Client request:

GET /chat HTTP/1.1
Host: ws.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Origin: https://example.com

Server response (agreeing to upgrade):

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

After 101, the TCP connection is now a WebSocket connection. HTTP is done; the WebSocket framing protocol takes over.

Server response (refusing to upgrade):

HTTP/1.1 426 Upgrade Required
Upgrade: websocket
Connection: Upgrade

A 426 Upgrade Required tells the client that the server requires a protocol upgrade to handle this request.

How 101 differs from a redirect

A redirect (301, 302) sends the client to a different URL. 101 Switching Protocols keeps the same TCP connection but changes the protocol speaking on it. The URL stays the same; everything below HTTP changes.

Upgrade and HTTP/2

Upgrade cannot be used in HTTP/2 or HTTP/3. HTTP/2 prohibits the Upgrade header. WebSocket over HTTP/2 uses a different mechanism: HTTP/2's CONNECT method with :protocol: websocket (RFC 8441). Existing WebSocket clients typically negotiate HTTP/1.1 for WebSocket connections specifically, even when HTTP/2 is available for regular requests.

Upgrade and proxies

Because Upgrade is listed in Connection, proxies must strip both headers before forwarding. This means Upgrade only applies to the next hop — the proxy itself, not the origin server. If you need to upgrade a connection through a proxy, the proxy must explicitly handle and forward the upgrade, which most reverse proxies (nginx, Apache, Caddy) support for WebSocket.

nginx WebSocket proxy configuration:

location /ws {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Common mistakes and gotchas

Forgetting Connection: Upgrade. Upgrade without Connection: Upgrade may be ignored or stripped by proxies. Always include both together.

Expecting Upgrade to work through all proxies automatically. Transparent proxies that don't understand WebSocket will strip Upgrade and Connection. You need explicit WebSocket proxy support configured at each hop.

Using Upgrade in HTTP/2. It's a protocol error. HTTP/2 clients attempting Upgrade will fail. Use the HTTP/2 WebSocket mechanism (RFC 8441) or negotiate HTTP/1.1 for WebSocket connections.

Real-world examples

WebSocket upgrade (most common use):

GET /realtime HTTP/1.1
Host: api.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=

Server requiring upgrade:

HTTP/1.1 426 Upgrade Required
Upgrade: websocket
Connection: Upgrade
Content-Type: text/plain

WebSocket connection required for this endpoint.

FAQ

Can Upgrade be used for anything besides WebSocket?

Yes. The spec allows any protocol: HTTP/2.0, TLS/1.0, IRC/6.9, custom protocols. In practice, WebSocket is virtually the only use case seen in the wild. HTTP/2 upgrade over HTTP/1.1 cleartext was specified (h2c) but never widely deployed because browsers only implement HTTP/2 over TLS.

What happens if the server doesn't support the requested upgrade?

The server can ignore Upgrade and respond normally with 200 OK (processing the HTTP request as-is), or respond with 426 Upgrade Required if it requires the upgrade to proceed.

Is there a way to force WebSocket without the upgrade handshake?

No — the Upgrade handshake is fundamental to WebSocket. It's how a WebSocket connection is established from HTTP. The only alternative is connecting directly to a port that only speaks WebSocket (without HTTP), which is non-standard.

Fun fact

The HTTP Upgrade mechanism predates WebSocket by a decade. It was designed in HTTP/1.1 (1997) with the vision of enabling smooth protocol evolution — an HTTP connection could upgrade to a newer HTTP version or any other protocol without a new TCP connection. In practice, the mechanism was rarely used until WebSocket arrived in 2011 and needed exactly this capability. WebSocket essentially saved Upgrade from being a specced-but-unused header, and Upgrade's existence made it possible for WebSocket to work over standard HTTP ports (80 and 443) without requiring dedicated infrastructure.