WebSocket connection failed: how to test it and what error 1006 means

When a browser says a WebSocket connection failed, the cause is nearly always one of a few: a proxy that doesn't pass WebSockets, a handshake the server refused, a certificate problem, or a connection cut for looking idle. To find out which, connect to the same address with our WebSocket test, read the close code, and then check the handshake.
This post goes through those steps, and the fix for each cause.
Why the browser tells you so little
Your code gets an error event with no details, followed by a close with code 1006. That code is never sent by a server. RFC 6455 reserves it for an endpoint to report a connection that ended with no close message, so it says only that something went wrong.
The vagueness is on purpose. If a page could tell a refused handshake from a closed port, a script could use it to scan the visitor's network. So the details are kept from your code, and you have to look elsewhere:
- The browser's developer tools. In the Network panel, filter by WS and select the connection. It shows the status of the handshake and every message.
- The console. The browser logs a reason there that your code can't read.
- The server's and the proxy's logs, which see what the browser hides.
Step 1: test the address
Open the WebSocket test, enter the wss:// address and connect. It logs how long the connection took, each message in both directions, and the close code with what it means.
If it connects here and not in your app, compare the two. This test has its own origin and none of your app's tokens, so the difference is usually authentication or a check on the origin. If it fails here too, try it from another network, such as a phone hotspot, to rule out a VPN or a company proxy.
Step 2: check the handshake
A WebSocket starts as an HTTP request, and curl shows you the answer that the browser hides:
curl -i -N --http1.1 \
-H "Connection: Upgrade" \
-H "Upgrade: websocket" \
-H "Sec-WebSocket-Version: 13" \
-H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
https://example.com/socketAdd -H "Origin: https://your-site.example" if your server checks where a connection comes from. The first line of the answer says most of it:
101 Switching Protocols. The handshake works, so look at what happens after it.200. The request reached an ordinary page, so the proxy isn't passing it on as a WebSocket, or the path is wrong.400. The server didn't accept the handshake. Some servers also expect more of a request than this one has.401or403. Authentication failed, or the origin isn't allowed.404. Nothing listens at that path.502,503or504. The proxy can't reach the server behind it.
If curl reports a certificate error, you have found the cause: a browser refuses the connection in the same way, and shows your code the same 1006.
The usual causes and their fixes
The proxy doesn't pass WebSockets. This is the most common one. A proxy has to forward the upgrade headers on purpose, and in nginx that looks like this:
location /socket {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
}It drops after about a minute. Proxies and load balancers close connections that look idle, and nginx's proxy_read_timeout is 60 seconds unless you change it. Raising it helps, but send a small message or a ping more often than the shortest timeout in the path, as you don't control every proxy between you and your users.
ws:// from an HTTPS page. Browsers block it as mixed content, apart from ws:// to localhost. Use wss:// on a page served over HTTPS.
The origin is refused. Servers often allow connections only from their own sites, and refuse the rest during the handshake. Add your site's address to the list.
There is no way to send headers. No browser can set headers on a WebSocket, so a token in an Authorization header never arrives. Send it in the query string, as a subprotocol, or in your first message.
It fails on every deploy. A restart drops every connection. Reconnect with a growing, random delay so that they don't all come back at once, and don't assume nothing was missed while away.
What the close codes say
Once a connection has opened, the code it closes with is worth reading:
- 1000: a normal closure, on purpose.
- 1001: going away, such as a server shutting down or the page being left.
- 1006: no close message, as above.
- 1008: the server refused under its rules, often authentication or the origin.
- 1011: something went wrong on the server.
- 1012 and 1013: a restart, or try again later.
The WebSocket test lists all of them with what they mean. Codes from 4000 up belong to the server or its library.
If you would rather not run the server
Most of this comes from running websockets yourself: the proxy, the timeouts, the restarts. Websockets in Python and Laravel go through what that takes in each framework, and why WordPress hosts cannot hold a websocket covers shared hosting.
With WordPlus Cloud, your app connects to our realtime servers through our SDKs, with rooms, presence and reconnects, and you run no WebSocket server. It is priced by connections, starting from 1,000, and the docs have a guide for each stack. If a connection to it fails, the connection test shows whether that network reaches our servers.