Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Socket.IO client fails to connect with xhr poll error

ErrorError: xhr poll error

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

  • Applies to socket.io 4, socket.io-client 4, React 19, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1curl 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. 2Requests go to /socket.io/ but the server was started with a custom path.The path option differs between server and clientFix
    3. 3The 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. 4Error code 5, Unsupported protocol versionClient and server use incompatible protocol versionsFix

What does the error look like?

  • Error: xhr poll error
  • connect_error: xhr poll error
  • Cross-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

Did this fix it?

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

Did this fix it?

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-control

Confirmed by socket.io

Did this fix it?

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-client

2Fix

Install matching major versions on both sides.

npm install socket.io-client@4

3Verify

Reload the app and watch for the connect event.

socket.on("connect", () => console.log("ok"));

Confirmed by socket.io

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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