A working command-line client does not guarantee that a browser can connect to the same endpoint. Start with the connection stage, then compare the URL, browser origin and application protocol. Use a test service you control and a harmless message.
Use the exact WSS endpoint
On an HTTPS page, use wss:// for a remote endpoint. Insecure ws:// can be blocked as mixed content; this is not evidence that the server is offline. Check the host, path and TLS certificate. Localhost exceptions and local-network permissions vary by browser.
wss://your-test-host.example/ws
Replace this placeholder with your own WebSocket endpoint.Connect before sending
Open the WebSocket tester, enter the endpoint and any documented subprotocol, then connect. Wait for OPEN. Send the smallest message accepted by your service; an arbitrary JSON message is not valid for every application protocol.
CONNECTING → OPEN → send a documented test message
Record the first response and the time until disconnect.Inspect the failed handshake
Check DevTools Network and Console alongside server or proxy logs. A 401/403 can point to authentication or an Origin policy; a 404 can indicate the wrong path. In an HTTP/1.1 upgrade, a successful handshake uses 101. The tester's error event alone cannot expose the underlying HTTP response or reliably identify a DNS, TLS or handshake failure.
Compare: URL/path · Origin · cookies · requested subprotocol
Then correlate the attempt with a server log timestamp.Interpret a close event
Code 1006 means the browser observed abnormal closure without receiving a Close frame. It is a symptom, not a specific timeout or authentication error. The peer must not send 1006 in a Close frame. Record whether OPEN occurred, how long the connection lasted and whether a proxy closed an idle connection.
1000: normal closure
1006: abnormal closure; inspect the handshake and server/proxy logsWhy can a CLI connect while the browser cannot?
The browser constructor accepts a URL and optional subprotocols, not arbitrary request headers. You cannot add an Authorization header or override Origin as you would with a CLI. Cookie authentication depends on the server and browser cookie policy. Follow the service's documented browser authentication flow; do not paste a production token into a URL. Adding CORS response headers alone does not replace WebSocket Origin validation.
Subprotocols are not custom headers
Enter only protocol names supported by the server, such as an application-specific version. These populate Sec-WebSocket-Protocol; they are not a free-form headers field. A negotiated protocol must match an offered value. If the service requires extra authentication messages, subscriptions or heartbeats after OPEN, follow that protocol before expecting application data.
Keep the next test focused
| Observation | Next check |
|---|---|
| Never reaches OPEN | Scheme, certificate, route, Origin and authentication |
| OPEN, then immediate close | Subprotocol and first application message |
| Disconnects after a repeatable idle period | Proxy timeout and documented heartbeat behavior |
| OPEN but no messages | Required subscription, destination and server-side events |
Official references
Protocol rules and browser API behavior were checked against these references. A browser tool cannot bypass the target service's authentication or security policy.
MDN — Browser client and secure connections
https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications
MDN — WebSocket constructor and subprotocols
https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket
WHATWG — WebSockets API, handshake and browser error reporting
https://websockets.spec.whatwg.org/
RFC 6455 — Origin checks (10.2) and close codes (7.4.1)
https://www.rfc-editor.org/rfc/rfc6455.html- Use WSS for remote connections from an HTTPS page.
- Separate handshake failure from application-message failure.
- Treat 1006 as a starting point for investigation, not a diagnosis.
- Browser headers, origins and subprotocol negotiation have specific constraints.