WebSocket Upgrade Failure PCAP Analysis

A site can serve ordinary HTTP normally while its live channel reports “WebSocket connection failed,” an unexpected response code, or a missing 101 Switching Protocols. In the capture, verify the Upgrade and Connection request headers, the proxy's response, TLS completion, and whether a reset occurs before or after the protocol switch; that separates an nginx WebSocket proxy-header problem from an application that closes an established socket. Encrypted payloads may hide header details without keys, but connection timing and TLS records still bound where the failure occurred. PCAP Surgery is useful because WebSocket traces often need both the HTTP handshake and the post-upgrade TCP timeline preserved.

What a healthy WebSocket upgrade looks like

A client sends an HTTP request with upgrade headers:

GET /socket HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: ...
Sec-WebSocket-Version: 13

The server replies:

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

After that, the connection is no longer ordinary HTTP request/response traffic. It carries WebSocket frames.

Common upgrade failures

Common causes include:

• Proxy strips Upgrade header.
• Proxy strips or rewrites Connection: Upgrade.
• Backend route does not support WebSocket.
• TLS termination sends request to wrong upstream.
• HTTP/2 to HTTP/1.1 upgrade behavior is misconfigured.
• Authentication redirect happens instead of 101.
• Backend returns 400, 403, 404, 426, 502, or 504.
• Connection resets after upgrade.
• Idle timeout closes quiet WebSocket.

The status code and headers matter.

Proxy header problems

Reverse proxies must forward WebSocket upgrade headers correctly. If the backend never sees Upgrade: websocket, it may treat the request as ordinary HTTP.

Packet evidence:

• Client-to-proxy request includes upgrade headers.
• Proxy-to-backend request lacks them.
• Backend returns normal HTTP response instead of 101.

That is a proxy configuration problem, not a WebSocket client bug.

TLS and SNI

For secure WebSocket (wss://), TLS happens before HTTP upgrade. If TLS fails, the WebSocket handshake never begins. Preserve DNS, TCP, TLS ClientHello, SNI, and any TLS alert or reset.

Do not diagnose upgrade headers until the TLS path is proven.

Connection drops after 101

Sometimes upgrade succeeds, then the connection closes. That is a different failure.

Look for:

• FIN or RST sender.
• Idle timeout duration.
• WebSocket ping/pong activity.
• Proxy read timeout.
• TCP retransmissions.
• Zero window.
• Backend process restart.

If the drop happens at a fixed interval, timeout policy is likely.

Checklist

Use this workflow:

1. Preserve DNS and TCP connect.
2. Verify TLS handshake for wss://.
3. Inspect client upgrade request headers.
4. Inspect server response status.
5. Confirm 101 Switching Protocols if expected.
6. Compare client-to-proxy and proxy-to-backend requests.
7. Look for redirects or auth responses.
8. If upgrade succeeds, inspect post-upgrade FIN/RST/timeout.
9. Preserve WebSocket ping/pong timing if visible.
10. Trim only after keeping the full handshake.

Final diagnosis

WebSocket upgrade failures are usually HTTP handshake or proxy-forwarding problems until 101 Switching Protocols is proven. After upgrade, failures become long-lived TCP timeout, reset, or application protocol problems.

PCAP Surgery helps preserve both phases so a vague WebSocket error can be traced to headers, proxy behavior, TLS, backend response, or connection lifetime.