Upgrade: switching protocols on an open connection
Upgrade asks to change the protocol used on the current connection. In practice that almost always means upgrading an HTTP/1.1 connection to WebSocket.
At a glance
- Direction
- Both. The client asks, and the server echoes the protocol it accepted.
- Defined in
- RFC 9110
- When absent
- The connection continues speaking HTTP, which is what nearly every request wants.
- Must accompany
- Connection: Upgrade, since the header is hop by hop
- Successful response
- 101 Switching Protocols, after which the bytes are no longer HTTP
- Refusal
- Any normal status. A server may simply ignore the request and answer 200.
- In HTTP/2
- Not available. Extended CONNECT is used instead, and there is no 101.
In detail
The client names a protocol it would rather speak, the server either agrees with 101 Switching Protocols or carries on as if nothing was asked. After a 101 the connection is no longer carrying HTTP messages at all, which is why response framing headers such as Content-Length have no meaning on that response.
The WebSocket handshake is the only common use. It pairs this header with a key that the server transforms and returns, so a client can tell a real WebSocket endpoint from a cache that happened to answer. Everything after the blank line belongs to the WebSocket protocol.
Because the header is hop by hop it must be accompanied by Connection: Upgrade, and every proxy on the path has to be configured to pass both along. That is why WebSocket connections fail behind an unconfigured reverse proxy with a 200 or a 400 instead of a 101: an intermediary stripped the headers and answered the request as ordinary HTTP.
HTTP/2 removed the mechanism. WebSocket over HTTP/2 uses an extended form of CONNECT, negotiated by a setting rather than by this header, and there is no 101 involved. Code that watches for that status to confirm a working WebSocket therefore needs a different check when the connection is HTTP/2.
Examples
GET /socket HTTP/1.1
Host: example.com
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=Things that catch people out
- Sending Upgrade without Connection: Upgrade means the request is not a valid upgrade attempt, and intermediaries will treat it as an ordinary request.
- A reverse proxy that is not configured for WebSocket strips both headers, and the handshake fails with an ordinary status rather than an error that mentions upgrading.
- There is no 101 on HTTP/2, so a health check that looks for that status reports a working endpoint as broken.
Try it: HTTP Headers Checker
Check a live URL or paste headers you already have. It grades six security headers from A+ to F and lists every other header the response returned.
HTTP Headers Checker
LOCAL · Browser-OnlyView HTTP response headers for any URL
Enter any website URL to fetch and analyze its HTTP response headers. We'll automatically add https:// if needed.
Why Check Security Headers?
Security headers protect your website against common attacks like XSS, clickjacking, and MIME sniffing. They're set by your web server and cost nothing to implement. Missing security headers are one of the most common findings in security audits.
Related HTTP headers
All http headers →Connection: keep-alive, close and hop by hop headers
What the Connection header controls, how it lists hop by hop headers, why HTTP/1.1 keeps connections open by default, and why HTTP/2 forbids it.
Alt-Svc: advertising an alternative endpoint
How Alt-Svc advertises another protocol or endpoint for the same origin, what ma and persist do, and why it is how most sites move clients to HTTP/3.
Transfer-Encoding: chunked framing on the connection
What chunked transfer encoding does, why it is a hop by hop property, why it must never accompany Content-Length, and why HTTP/2 forbids it entirely.
Host: which site the request is for
Why Host is mandatory in HTTP/1.1, how it maps to the authority in HTTP/2 and HTTP/3, and why trusting it to build URLs creates a real vulnerability.
Link: relationships expressed in a header
How the Link header carries relationships that markup cannot, its use for preload with early hints, and the pagination pattern that APIs build on it.
Server-Timing: server side metrics in the response
How to report server side durations to the browser, the dur and desc parameters, what it costs to expose them, and how to read them cross-origin.
Tools for this
- HTTP Request Builder Free online HTTP request builder - build and test HTTP requests with custom headers and body
- HTTP Headers Checker Free online HTTP headers checker - view HTTP response headers for any URL