WebSocket Tester

Debugging WebSockets is mostly reading close codes

WebSocket debugging has an awkward property: when something goes wrong, the browser tells your JavaScript almost nothing. The error event carries no message, no status, no stack — this is deliberate, to stop scripts from probing services the page should not see into. All the signal is in the close event: a numeric code, an optional reason string, and a clean/unclean flag. Code 1000 is a normal goodbye; 1006 means the connection died without a close frame (wrong URL, server down, handshake rejected, proxy in the way); 1008 is the server enforcing a policy such as authentication; 1011 is the server admitting an internal error. This tool looks up every code it sees and prints the meaning next to it, which turns the usual "it just disconnects" mystery into an actual diagnosis.

The other classic failure is mixed content. A secure page may only open secure sockets, so ws:// from an https page is blocked before it ever reaches the network — with localhost as the notable exception in Chrome and Firefox, which treat your own machine as trustworthy. That exception is what makes this page useful against a dev server: connect to ws://localhost:8080 and it behaves exactly like your own frontend code would.

Related tools

WebSockets usually live next to a plain HTTP API. Fire test POSTs at callback URLs with the Webhook Tester, or craft any request — method, headers, auth, body — in the HTTP Request Builder. If your socket speaks JSON, the JSON Formatter helps with payloads too large for the inline pretty-printer.

Frequently asked questions

What is the difference between ws:// and wss://?

ws:// is the plain WebSocket protocol and wss:// is the same protocol over TLS — the exact relationship http:// has to https://. wss:// encrypts the connection and is what you should use in production. It also matters for where you can test from: a page served over https (like this one) can open wss:// connections freely, but plain ws:// connections are treated as mixed content and blocked by the browser.

Why does my connection fail from this page?

The most common cause is mixed content: this page is served over https, and browsers block insecure ws:// connections from secure pages, usually before a single packet is sent. Use wss:// instead. Other frequent causes: the server is not actually speaking WebSocket on that path (you get an immediate close with code 1006), a proxy or load balancer in front of the server does not forward Upgrade requests, or the server requires a subprotocol you did not offer. Browsers deliberately hide low-level error details from JavaScript, so the close code is usually the best clue you get.

What do the close codes mean?

When a WebSocket closes, the close frame carries a numeric code. 1000 is a normal closure and 1001 means the endpoint is going away (server shutdown or page navigation). 1006 is the one you will see most while debugging: it means the connection died with no close frame at all — server unreachable, handshake rejected, or network dropped. 1008 is a policy violation (e.g. auth failure), 1009 means your message was too big, and 1011 is a server-side internal error. Codes 4000–4999 are app-defined, so their meaning is whatever the server says it is. The tool looks up each code and shows its meaning in the log.

How do I test a server running on my own machine?

Point the tool at ws://localhost:PORT (or ws://127.0.0.1:PORT). Even though this page is https, Chrome and Firefox treat localhost as a trustworthy origin, so plain ws:// to localhost is allowed from a secure page. Safari is the exception — it may still block the connection; if it does, test from Chrome or Firefox, or put TLS in front of your dev server. No local server handy? npx wscat --listen 8080 gives you an interactive WebSocket server on ws://localhost:8080 in one command.

Is there a public endpoint I can test against?

Yes — wss://echo.websocket.org is a free public echo server (run by Ably) that sends every message straight back to you, which makes it perfect for a first smoke test of this tool or your own client code. Messages are capped at 64 KB and idle connections time out after 10 minutes. For anything private, prefer a local server: npx wscat --listen 8080, then connect to ws://localhost:8080.

What are subprotocols?

Subprotocols let the client and server agree on the application-level protocol spoken over the socket — for example graphql-ws for GraphQL subscriptions or mqtt for MQTT over WebSocket. The client offers a list during the handshake and the server picks one (or rejects the connection). Enter them comma-separated before connecting; the log shows which one the server selected. Most plain WebSocket servers need none.

Do my messages go through your servers?

No. The browser opens the WebSocket connection directly from your machine to the endpoint you enter — there is no proxy in between, and nothing about your session is sent to us. That also means the connection behaves exactly as it would in your own frontend code: same TLS rules, same mixed-content restrictions, same close codes.