WebSocket handshake fails with HTTP 400 against a Socket.IO server
WebSocket connection to 'wss://example.com/socket.io/?EIO=4&transport=websocket' failed: Error during WebSocket handshake: Unexpected response code: 400Short 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.
Fix it fast
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"2Match what you see, then jump to its fix
- 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
{"code":3,"message":"Bad request"}, polling works but the upgrade to WebSocket failsThe proxy does not forward the Upgrade headersFix - 3
{"code":5,"message":"Unsupported protocol version"}An older Socket.IO client talks to a v3 or v4 serverFix
- 1
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 nginxConfirmed by socket.io
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 nginxConfirmed by nginx.org
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 80Confirmed by socket.io
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
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 fixBack end
Socket.IO answers 404 on the polling request
Cannot GET /socket.io/
A 404 on /socket.io/?EIO=4&transport=polling means the request is not reaching a Socket.IO server.
3 causes, each with a fixBack end
Express rejects a request body as too large
413 (Request Entity Too Large) returned by nginx in front of the app
A 413 means a body was bigger than a size limit.
3 causes, each with a fixBack end
The browser says io is not defined, or socket.io.js is not found
GET http://localhost:3000/socket.io/socket.io.js 404 (Not Found)
io is not defined means the Socket.IO client script never loaded.
3 causes, each with a fixBack end
Multer upload fails with 'Unexpected end of form'
Error: Unexpected end of form
Multer reads multipart bodies with busboy, which raises this error when the request body ends before the closing boundary line.
2 causes, each with a fixBack end
Node.js fetch fails with unable to get local issuer certificate
code: 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY'
Node cannot link the server's certificate to a CA it trusts.
3 causes, each with a fix