Go client fails with 'websocket: bad handshake'
websocket: bad handshakeShort answer
bad handshake means the server answered the upgrade request with something other than a valid WebSocket handshake. Dial returns the HTTP response with the error, so print its status code first. A common case is a Socket.IO server: it needs the /socket.io/ path with EIO=4 and transport=websocket in the URL.
Fix it fast
1Find out which cause you have
Dial returns the HTTP response when the handshake fails. Print the status code and body so you see what the server actually said.
c, resp, err := websocket.DefaultDialer.Dial(url, nil) if err != nil { if resp != nil { body, _ := io.ReadAll(resp.Body) log.Printf("status=%d body=%s", resp.StatusCode, body) } log.Fatal(err) } defer c.Close()2Match what you see, then jump to its fix
What does the error look like?
websocket: bad handshake
Cause 1 of 2
The URL points at a Socket.IO server, not a plain WebSocket endpoint
1Check
Socket.IO runs on Engine.IO. A raw WebSocket client must use the /socket.io/ path with the EIO and transport query parameters, both mandatory; a server closes the connection if one is missing.
echo "$WS_URL"2Fix
Use the Engine.IO form of the URL. After connecting, the server sends an open packet and then pings, which the client must answer, so a plain client needs to speak that protocol. A Socket.IO client library is usually simpler.
url := "wss://example.com/socket.io/?EIO=4&transport=websocket"3Verify
Dial succeeds and the first message read starts with 0 followed by JSON that contains sid.
_, msg, _ := c.ReadMessage()
log.Println(string(msg))Confirmed by socket.io
Cause 2 of 2
The server returns an HTTP response that is not 101
1Check
The library returns ErrBadHandshake when the server response to the opening handshake is invalid, together with the response, so redirects and authentication can be handled. The status code shows which of those it is.
log.Println(resp.StatusCode, resp.Header)2Fix
Fix what the status says: correct the path, send the credentials the server wants in the request header you pass to Dial, or dial the final URL after a redirect.
header := http.Header{}
header.Set("Authorization", "Bearer "+token)
c, resp, err := websocket.DefaultDialer.Dial(url, header)3Verify
Dial returns a nil error and resp.StatusCode is 101.
log.Println(resp.StatusCode)Confirmed by pkg.go.dev
How do I stop it coming back?
- Always log resp.StatusCode when Dial fails; the error text alone does not carry it.
- Check the server's own docs for the exact WebSocket path and required query parameters.
- Set Dialer.HandshakeTimeout so a stuck server does not hang the client.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Related fixes
Back end
Airflow SSHOperator stops a long script with SSH command timed out
airflow.exceptions.AirflowException: SSH command timed out
SSHOperator waits only 10 seconds for a command by default.
3 causes, each with a fixBack end
Android gets HTML instead of JSON from a PHP API
org.json.JSONException: Value <br of type java.lang.String cannot be converted to JSONObject
The response body is not JSON.
2 causes, each with a fixBack end
ng serve says it cannot determine the project or target
Cannot determine project for command.
The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.
3 causes, each with a fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack end
ng serve cannot find the dev-server builder package
Could not find the implementation for builder @angular/build:dev-server
The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.
3 causes, each with a fix