Socket.IO client fails to connect with xhr poll error
Error: xhr poll errorShort answer
xhr poll error is only the reason string on the client's connect_error event: the first HTTP request to the server failed. Log the error details, then request the server's polling URL with curl. The usual causes are a wrong server URL, a path option that differs between client and server, and CORS not enabled on the server.
Fix it fast
1Find out which cause you have
Add a connect_error listener and log the details, then test the server URL directly. The curl call should return a handshake payload; if it does not, the server or URL is the problem.
socket.on("connect_error", (err) => { console.log(err.message); console.log(err.description); console.log(err.context); }); curl "http://localhost:3000/socket.io/?EIO=4&transport=polling"2Match what you see, then jump to its fix
- 1
curl to /socket.io/?EIO=4&transport=polling fails or returns a non-Socket.IO page.The client points at a URL where no Socket.IO server answersFix - 2
Requests go to /socket.io/ but the server was started with a custom path.The path option differs between server and clientFix - 3
The browser console reports a blocked cross-origin request or a missing Access-Control-Allow-Origin header.CORS is not enabled on the server (React on another origin)Fix - 4
Error code 5, Unsupported protocol versionClient and server use incompatible protocol versionsFix
- 1
What does the error look like?
Error: xhr poll errorconnect_error: xhr poll errorCross-Origin Request Blocked: ... (Reason: CORS header 'Access-Control-Allow-Origin' missing)
Cause 1 of 4
The client points at a URL where no Socket.IO server answers
1Check
Open the URL the client uses (check the value passed to io()) and run the curl call from the first step against it. The docs ask you to verify the server is reachable this way.
grep -rn "io(" src/
curl "http://localhost:3000/socket.io/?EIO=4&transport=polling"2Fix
Pass the real server address to io(), including the port, and make sure the server process is running and listening.
import { io } from "socket.io-client";
const socket = io("http://localhost:3000");3Verify
Run the curl again; the connect event should then fire in the browser.
socket.on("connect", () => console.log("connected", socket.id));Confirmed by socket.io
Cause 2 of 4
The path option differs between server and client
1Check
Look for a path option on both sides. The client and server values must match.
grep -rn "path:" server/ src/2Fix
Use the same path on both sides.
// server
const io = new Server(httpServer, { path: "/my-custom-path/" });
// client
const socket = io("http://localhost:3000", { path: "/my-custom-path/" });3Verify
Run curl against the custom path (replace /socket.io/ with it) and confirm a handshake payload comes back.
curl "http://localhost:3000/my-custom-path/?EIO=4&transport=polling"Confirmed by socket.io
Cause 3 of 4
CORS is not enabled on the server (React on another origin)
1Check
Since Socket.IO v3, CORS must be enabled explicitly. A React dev server on port 5173 talking to a server on port 3000 is a different origin.
grep -rn "cors" server/2Fix
Allow the exact origin of your React app in the server options.
import { Server } from "socket.io";
const io = new Server(httpServer, {
cors: {
origin: ["http://localhost:5173"]
}
});3Verify
Restart the server and reload the page; the CORS error should disappear and connect should fire.
curl -i -H "Origin: http://localhost:5173" "http://localhost:3000/socket.io/?EIO=4&transport=polling" | grep -i access-controlConfirmed by socket.io
Cause 4 of 4
Client and server use incompatible protocol versions
1Check
Compare the socket.io and socket.io-client versions in both package.json files.
npm ls socket.io socket.io-client2Fix
Install matching major versions on both sides.
npm install socket.io-client@43Verify
Reload the app and watch for the connect event.
socket.on("connect", () => console.log("ok"));Confirmed by socket.io
How do I stop it coming back?
- Read the server address and path from one environment variable shared by dev and build.
- Keep the client and server on the same Socket.IO major version.
- Keep a connect_error logger in the client during development.
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.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
Related fixes
Web apps
Axios sends no cookie to an Express API even with withCredentials set to true
The login response has a Set-Cookie header, but the browser stores nothing
withCredentials only tells the browser to attach cookies.
4 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Can't resolve '../axios' in a React project
Module not found: Error: Can't resolve '../axios'
A path that starts with ./ or ../ is a file path, not the axios package.
3 causes, each with a fixWeb apps
Axios returns 401 from a React app but the login works elsewhere
Error: Request failed with status code 401
A 401 means the server received the request without valid credentials.
3 causes, each with a fix