How to Debug WebSocket Connections with HTTP Debugger

WebSocket is a full-duplex, bidirectional protocol that keeps a persistent channel open over a single, long-lived TCP connection. A connection begins as an ordinary HTTP request and then upgrades in place to a persistent channel, after which either side can send a message at any time without waiting for the other.

Unlike a REST request/response pair — or the strictly typed remote procedure calls of gRPC — WebSocket is a raw channel that carries whatever framing your application puts on it, most often JSON, sometimes binary. Many UIs for AI agents use the WebSocket protocol for live status messages, tool-call events, and interrupts.

To debug a WebSocket connection you cannot just read a URL and a response body the way you do with REST. The useful signal is spread across two layers: the handshake that opens the channel — an HTTP/1.1 upgrade or an HTTP/2 extended CONNECT — and every frame that flows over it afterward, including data frames, keepalives, and a final close code. The sections below cover what a WebSocket connection actually looks like on the wire, the frame and close-code details that explain real failures, and how to inspect live WebSocket traffic without a proxy or browser extension.

What to inspect when you debug a WebSocket connection

A complete WebSocket debugging pass covers four layers, listed here in the order the connection builds them — though a close code, when you have one, is usually where you start:

1. The handshake — either the HTTP/1.1 GET request with Upgrade: websocket and a 101 Switching Protocols response, or the HTTP/2 CONNECT request with :protocol set to websocket and a :status of 200. If this fails, no frames are ever exchanged.
2. Data frames — the Text and Binary messages your application actually sends and receives, plus their direction and timing.
3. Control frames — Ping/Pong keepalives and the Close frame, which explain idle drops and disconnects.
4. The close code — the numeric reason the connection ended, which is often the single most useful clue.

How the WebSocket protocol works under the hood

Most connection bugs are easier to read once you know what the bytes mean. WebSocket is defined by RFC 6455, and compression by RFC 7692.

The HTTP/1.1 upgrade handshake

A WebSocket often begins as an ordinary HTTP/1.1 request. The client sends an Upgrade request with a random Sec-WebSocket-Key; the server confirms with 101 Switching Protocols and a matching Sec-WebSocket-Accept. The accept value is not a secret — it is the SHA-1 hash of the client key concatenated with the fixed GUID 258EAFA5-E914-47DA-95CA-C5AB0DC85B11, Base64-encoded. A mismatched or missing accept header means a proxy or server mangled the handshake.

GET /chat HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Sec-WebSocket-Extensions: permessage-deflate

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

The same handshake also carries the negotiated subprotocol (Sec-WebSocket-Protocol) and extensions (Sec-WebSocket-Extensions). Reading these HTTP headers tells you whether compression was actually agreed, not just requested.

WebSocket over HTTP/2

WebSocket can also run over HTTP/2 using extended CONNECT. In that flow there is no 101 Switching Protocols response. The client opens an HTTP/2 stream with :method set to CONNECT and :protocol set to websocket; the server accepts it with :status: 200. After that, the HTTP/2 stream carries the same WebSocket frame format: text, binary, continuation, ping, pong, and close frames.

# HTTP/2 request headers
:method: CONNECT
:scheme: https
:authority: example.com
:path: /chat
:protocol: websocket

# HTTP/2 response headers
:status: 200

Frame anatomy and opcodes

After the WebSocket is established, data travels in frames rather than messages. Each frame begins with a FIN bit (is this the last fragment?), three reserved bits — RSV1 marks the first frame of a compressed message when permessage-deflate is used — a 4-bit opcode, a MASK bit, and a payload length encoded in 7, 7+16, or 7+64 bits. The opcode decides how to read the rest:

Two details commonly cause confusion. First, every client-to-server frame is masked: the payload is XOR-ed with a 4-byte key, so a raw capture of an outgoing frame looks like noise until it is unmasked. Server-to-client frames are never masked. Second, a single logical message can be fragmented across one initial frame (FIN=0) and any number of Continuation frames, which is why a payload may appear to arrive in pieces.

Control frames and compression

Ping and Pong frames keep an otherwise idle connection alive; if a load balancer or proxy times out before the next ping, you get an abnormal close. A Close frame carries a 2-byte close code followed by an optional UTF-8 reason string. When permessage-deflate is negotiated, individual text and binary messages can be DEFLATE-compressed. The first frame of a compressed message sets the RSV1 bit; continuation frames inherit that compressed message state even though they do not set RSV1 themselves. The client_no_context_takeover and server_no_context_takeover parameters control whether the compression window resets between messages. A capture that does not inflate those messages shows compressed bytes instead of your JSON.

WebSocket close codes worth knowing

These are the close codes you will see most while debugging:

Codes 1005, 1006, and 1015 are never sent on the wire — the browser or runtime sets them locally when no real close frame arrived. That is why a 1006 never has a reason string: the connection died before a Close frame could be exchanged. To find the cause, you have to look one layer down at the handshake, the last frames before the drop, and the keepalive timing — not at the close event itself.

How to debug WebSocket connections step by step

There are two ways to debug a WebSocket connection. If it already closed, you have a close code — read it first and work backward. When nothing has clearly failed, make a full pass through the steps below in order.

1. Confirm the handshake. For HTTP/1.1, verify the request carries Upgrade: websocket and the response is 101 Switching Protocols with a valid Sec-WebSocket-Accept. For HTTP/2, verify :method: CONNECT, :protocol: websocket, and :status: 200. A redirect, forbidden response, or ordinary 200 OK HTTP/1.1 page means the WebSocket setup was blocked or rewritten upstream.
2. Read the frames in order. Follow sent and received frames on a single timeline, checking opcode and direction so you can see which side stopped talking and when. Remember that client-to-server frames are masked, so a raw outgoing payload looks like noise until it is unmasked, and a single message can span an initial frame plus Continuation frames.
3. Decode the payload. Inflate frames marked as compressed after permessage-deflate negotiation and pretty-print JSON so you compare application data, not compressed bytes. Confirm text frames are valid UTF-8.
4. Check keepalive and close. Look at Ping/Pong spacing for idle drops, and read the Close code and reason to separate a clean shutdown from a network or server failure.

Ways to debug WebSocket connections

Each approach sees a different slice of the connection. Browser tooling is closest at hand but only for pages you load yourself; packet capture sees everything but at a low level; in-app logging shows decoded messages but only for code you control.

Browser DevTools is the fastest path for a page you control, and a packet capture is the most thorough at the network layer. The gap each one leaves is the WebSocket you cannot load in a tab or instrument yourself.

From the shell, the fastest first check is to open the handshake directly with a CLI client:

wscat -c wss://api.example.com/chat

If wscat (or websocat) completes the handshake and echoes messages but your app does not, the difference is on the client — headers, subprotocol, or auth. If the handshake fails here too, the problem is the server or a hop in between. A CLI client confirms the upgrade and prints decoded messages, but it does not show frame internals like opcodes, masking, or compression — for that you need a capture.

Debug WebSocket connections with HTTP Debugger

HTTP Debugger captures WebSocket traffic and keeps it visible in the same grid as the rest of the session. Each connection shows its method, URL, status, type, size, and timing, then opens into a dedicated Messages pane for per-frame inspection.

Common WebSocket debugging scenarios

"The connection closes immediately with 1006"

A 1006 right after opening usually means the handshake never really succeeded or was torn down before any frame arrived. Confirm a 101 (or HTTP/2 200) actually came back; a redirect, a 200 OK HTML page, or a stripped Sec-WebSocket-Accept means a proxy or gateway intercepted the upgrade. For wss://, a failure during TLS surfaces locally as 1015.

"Messages stop arriving after a while"

Look at the Ping/Pong spacing leading up to the silence. When an idle connection sends no keepalives, a load balancer or reverse proxy will close it on its own timeout — often surfacing as 1001 or a bare 1006 with no reason. The gap between the last data frame and the drop tells you whether it was idle.

"The handshake returns 200 or a redirect instead of 101"

The request never reached the WebSocket endpoint as an upgrade. An authenticating proxy, a CDN, or a gateway handled it as plain HTTP and stripped the Upgrade and Connection headers, or routing sent it to a default handler. Compare the request headers that left the client with the response: if Upgrade: websocket went out but did not come back acknowledged, the hop in between is the suspect.

"The payload looks like binary garbage"

Either the message is genuinely binary (opcode 0x2), or permessage-deflate was negotiated and the frame is DEFLATE-compressed with RSV1 set on the first frame. Inflate it before judging the contents; only then can you tell corrupt data from compressed-but-valid JSON.

"It works locally but breaks behind a proxy"

Reverse proxies and load balancers are the most common cause of WebSocket failures that never reproduce on localhost. They may not forward the Upgrade header, may buffer frames instead of streaming them, or may apply an idle timeout shorter than your keepalive interval. Capture the connection through the proxy and compare its handshake headers and frame timing against a direct connection.

Limitations

System-wide capture shows exactly what crossed the wire, but it does not rewrite it. WebSocket traffic in HTTP Debugger is read-only: it decodes and inspects frames rather than injecting or modifying them, and the Auto-Reply and HTTP Modifier rules apply to regular HTTP/HTTPS traffic, not WebSocket frames. Frame decoding also has size and format limits, so very large or unusual payloads may show as raw bytes rather than fully decoded text. Capture is Windows-only and reads the connection at the protocol layer, not your application's message schema. For everything around the frames — headers, timing, sizes, and the raw HTTP protocol exchange — the HTTP analyzer and the system-wide HTTP sniffer cover the rest. The same workflow applies to the rest of the stack — see the guides on debugging the HTTP/2 traffic a connection can ride on, plus gRPC calls and SSE streams.

FAQ