Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Go client fails with 'websocket: bad handshake'

Errorwebsocket: bad handshake

Short 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.

  • Applies to Go 1.23, gorilla/websocket 1.5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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()
  2. 2Match what you see, then jump to its fix

    1. 1The server is a Socket.IO server and the dial URL has no /socket.io/ path or lacks the query parametersThe URL points at a Socket.IO server, not a plain WebSocket endpointFix
    2. 2resp.StatusCode is a redirect, 401, 403 or 404 instead of 101The server returns an HTTP response that is not 101Fix

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

Did this fix it?

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

Did this fix it?

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

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 fix

Back 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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.