A reverse proxy now sits in front of your WebSocket service and clients get 200 OK with an HTML body instead of 101. What happened?

## Read the symptom precisely The client sent a WebSocket handshake and got back a complete, well-formed HTTP response: `200 OK`, a content type, a length, a body. That is not a timeout, not a reset, and not a refused connection. Something answered the request *as a request*. Either the intermediary answered it, or it forwarded something that no longer looked like an upgrade — and the second is by far the more common. ## Why the fields disappear by design `Upgrade` and `Connection` are **connection-scoped**: they describe what is to happen on the one hop they arrived on, not an instruction addressed to the far end of a chain. `Connection` is itself the field that designates which other fields are scoped that way, and on a WebSocket handshake it designates `Upgrade`. An intermediary is therefore supposed to consume them and make its own decision about its own upstream connection. So the default behaviour of a general-purpose intermediary is not a bug — it is the rule being followed. Forwarding a handshake means *deliberately re-creating* it on the next hop, which is why proxying a socket is always a configuration and never an accident: 1. re-issue `Upgrade: websocket` and `Connection: Upgrade` on the upstream request; 2. speak HTTP/1.1 upstream — an HTTP/1.0 hop has no upgrade mechanism, so the handshake cannot survive it; 3. when `101 Switching Protocols` comes back, stop treating the connection as a request/response exchange and relay raw bytes in both directions until either side closes; 4. give that connection a far longer idle allowance than an ordinary request, because a healthy socket may carry nothing for minutes. Step 3 is where the second class of failure lives. An intermediary that forwards the fields but does not know what to do with a `101` may tear the connection down or report a gateway error instead of tunnelling. ## The three shapes of the same misconfiguration | what the client sees | what happened | |---|---| | `200 OK` with a page body | the fields were dropped, the origin answered the path as an ordinary GET | | `404` or a redirect | the fields were dropped **and** the path is not one the origin serves normally | | `502 Bad Gateway` | the fields arrived, but the hop could not carry or interpret the upgrade upstream | | handshake completes, then dies quietly seconds later | the tunnel was established but the hop applies an ordinary request idle allowance | The first three are all visible in the handshake, which makes them cheap to diagnose: capture the exact request the origin received. If `Upgrade` and `Connection` are missing there but present in what the client sent, you have your answer in one line and the change is on the intermediary, not in your service. ## Why this is misdiagnosed The response body is a page, so the first instinct is a routing problem — wrong host, wrong path, wrong virtual server. The routing is usually fine. The request reached exactly the handler it was aimed at; that handler simply received a request with no upgrade in it and did the only thing it could. A second instinct is to blame encryption: "the hop is TLS-terminated, so the intermediary could not read the fields." Terminating TLS is precisely what lets it read them — an intermediary that terminates reads and re-creates the whole request, and the fields are dropped in that re-creation. ## On the occupancy board The board's socket runs through an edge terminator, a caching layer and a municipal filtering appliance. Each is a hop, and each has to be told to carry the upgrade; one that has not been will silently degrade the handshake into an ordinary request and hand the board back its own dashboard page. The useful engineering habit is to treat the handshake as an end-to-end contract you test per hop: send the upgrade at each boundary in turn and check for `101 Switching Protocols`. The first hop that answers `200 OK` is the one holding the configuration you are missing, and the rest of the chain is innocent. A final operational note: because the upgrade rides a plaintext scheme so much more often on internal hops, the hop most likely to mangle the handshake is the one where the bytes are inspectable. A hop that tunnels an encrypted connection has nothing to re-create and nothing to drop.