Maaz Zindani

Loading the index…

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

WebSocket handshake fails with HTTP 400 against a Socket.IO server

ErrorWebSocket connection to 'wss://example.com/socket.io/?EIO=4&transport=websocket' failed: Error during WebSocket handshake: Unexpected response code: 400

Short answer

A 400 during the handshake means the server understood the request and rejected it. For Socket.IO the response body holds a numeric code that names the reason. The common ones are a load balancer that does not keep one client on one server, a proxy that drops the Upgrade headers, and a client and server on incompatible protocol versions.

  • Applies to Socket.IO 4, nginx 1.26, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the failing request in DevTools or repeat it with curl and read the JSON body. The code field tells you which cause below applies.

    curl -i "https://example.com/socket.io/?EIO=4&transport=polling"
  2. 2Match what you see, then jump to its fix

    1. 1{"code":1,"message":"Session ID unknown"}, often only after you scaled to a second process or machineSeveral servers behind a balancer without sticky sessionsFix
    2. 2{"code":3,"message":"Bad request"}, polling works but the upgrade to WebSocket failsThe proxy does not forward the Upgrade headersFix
    3. 3{"code":5,"message":"Unsupported protocol version"}An older Socket.IO client talks to a v3 or v4 serverFix

What does the error look like?

  • WebSocket connection to 'wss://example.com/socket.io/?EIO=4&transport=websocket' failed: Error during WebSocket handshake: Unexpected response code: 400
  • {"code":1,"message":"Session ID unknown"}
  • {"code":3,"message":"Bad request"}
  • {"code":5,"message":"Unsupported protocol version"}

Cause 1 of 3

Several servers behind a balancer without sticky sessions

1Check

A Socket.IO session starts with polling requests and then upgrades. Every request of one session must reach the same server, or the second server returns 400 because it never saw the session id. Count how many processes sit behind the proxy.

pm2 list
grep -n -A6 "upstream" /etc/nginx/conf.d/*.conf /etc/nginx/sites-enabled/*

2Fix

Make the balancer sticky. The Socket.IO docs show nginx hashing the client address in the upstream block; ip_hash is the alternative.

upstream nodes {
    hash $remote_addr consistent;
    server 10.0.0.11:3000;
    server 10.0.0.12:3000;
}

3Verify

Reload nginx and open several connections from one client; none should end in 400.

sudo nginx -t && sudo systemctl reload nginx

Confirmed by socket.io

Did this fix it?

Cause 2 of 3

The proxy does not forward the Upgrade headers

1Check

Upgrade and Connection are hop-by-hop headers, so nginx does not pass them on unless told to. The server then never receives the Connection: upgrade it needs.

sudo nginx -T 2>/dev/null | grep -n -i "upgrade\|proxy_http_version"

2Fix

Forward both headers on the location that serves Socket.IO. Use the map form so ordinary requests are not marked as upgrades.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

location /socket.io/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;
}

3Verify

Reload nginx and reconnect; the browser's network tab should show a 101 Switching Protocols response.

sudo nginx -t && sudo systemctl reload nginx

Confirmed by nginx.org

Did this fix it?

Cause 3 of 3

An older Socket.IO client talks to a v3 or v4 server

1Check

The troubleshooting guide says a v1 or v2 client hitting a newer server gets this 400. Look at the EIO number in the request URL and at the installed client version.

npm ls socket.io socket.io-client
curl -s "http://localhost:3000/socket.io/?EIO=3&transport=polling"

2Fix

Upgrade the client to the same major version as the server. If old clients cannot be updated yet, let the server accept them for now.

const io = new Server(httpServer, { allowEIO3: true });

3Verify

Connect once with the old client and once with the new one.

curl -s "http://localhost:3000/socket.io/?EIO=3&transport=polling" | head -c 80

Confirmed by socket.io

Did this fix it?

How do I stop it coming back?

  • Decide on sticky sessions before you run a second Node.js process, not after the first 400s.
  • Keep the Socket.IO server and client on the same major version in one lockfile policy.
  • Test the public URL, not only localhost, since the proxy is where headers get lost.

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.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

The browser blocks your API response: no Access-Control-Allow-Origin header

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://api.example.com/orders. (Reason: CORS header 'Access-Control-Allow-Origin' missing).

The browser received the response but refused to hand it to your script, because it did not carry an Access-Control-Allow-Origin header naming the page's origin.

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