Invalid handshake error when Socket.IO v4 server receives v3 client connection

Direct Answer

A Socket.IO v4 server rejects a v3 client because the handshake logic performs a hard-coded major-version comparison before any transport negotiation or middleware runs. The server extracts the client's version from the query parameter v=3.x.x, parses the major component, and compares it against its own major version. If they differ, the handshake is aborted with "Invalid handshake". No server configuration option or documented middleware can bypass this check.

Exact Version-String Comparison

The server reads the v query string sent by the client during the initial HTTP handshake, e.g. v=3.1.4. It then executes logic equivalent to:

const clientMajor = parseInt(clientV.split('.')[0], 10); const serverMajor = parseInt(serverV.split('.')[0], 10); if (clientMajor !== serverMajor) { rejectHandshake(); }

This check runs in the Socket.IO handshake layer, before Engine.IO transport selection, CORS evaluation, or any io.use() middleware.

Server Configuration Cannot Bypass the Check

The following options have no effect on the major-version validation:

• origins / CORS settings
• transports (websocket, polling)
• pingTimeout, pingInterval
• allowEIO3 (controls Engine.IO protocol version, not Socket.IO major version)
• Custom middleware via io.use((socket, next) => ...)

All of these are applied after the handshake version check has already terminated the connection.

No Documented Extension Points for Custom Handshake Validation

Socket.IO v4 exposes extension points such as:

• io.use() for per-socket authorization (runs after handshake)
• io.engine.on('connection') for raw Engine.IO sockets (runs after handshake)

Neither provides a hook to intercept or override the major-version comparison. The validation is internal to the handshake module and not designed to be extensible.

Verification Steps

1. Create a minimal v4 server: npm i socket.io@4
2. Create a v3 client: npm i socket.io-client@3
3. Start the server and connect the client.
4. Observe the server console logging "Invalid handshake" and the client emitting an error event followed by disconnection.
5. Optionally, add io.use() middleware or listen on io.engine.on('connection') and confirm they are never invoked for the v3 client.

Practical Resolution

To establish a connection, you must either:

• Upgrade the client to Socket.IO v4 (recommended), or
• Downgrade the server to Socket.IO v3.

Modifying the library source to disable the check is unsupported and will likely break with future updates due to protocol incompatibilities between major versions.

One Diagnostic Detail That Could Change the Recommendation

If you are using a load balancer, proxy, or custom transport layer that might rewrite the v query parameter, confirm the exact query string received by the Socket.IO server. A mismatched or stripped v parameter would produce the same symptom but for a different reason.