Socket.IO "Timeout" waiting for connection in CI tests

By Daniel Zoghalchali·Latchkey

Socket.IO emits connect_error with message "timeout" when the handshake does not complete within timeout (20s by default). Under a loaded CI runner the server can be slow enough that the client gives up.

What this error means

A test that awaits the connect event times out, or the client fires connect_error with err.message === "timeout". It passes locally and flakes on shared CI runners.

connect_error Error: timeout
    at Timeout._onTimeout (node_modules/socket.io-client/build/cjs/manager.js:...)

Common causes

The server is slow to accept under CI load

A CPU-starved runner delays the server's handshake past the client timeout, so the connect never resolves in time.

The test awaits connect before the server is up

The test opens the client and immediately awaits connect while the server is still initializing, burning the whole timeout window.

How to fix it

Await the connect event with an explicit handler

1. Wrap the connect in a promise that resolves on connect and rejects on connect_error.
2. Only start the timer after the server is confirmed listening.
3. Raise the client timeout if runners are consistently slow.

await new Promise((resolve, reject) => {
  client.on('connect', resolve);
  client.on('connect_error', reject);
});

Give slow runners more time

Increase the Socket.IO connect timeout so a slow but healthy server still connects.

const client = io(url, { timeout: 60000 });

How to prevent it

• Sequence the server-listen and client-connect so the timer starts fairly.
• Set a realistic timeout for the slowest runners in the fleet.
• Avoid connecting many clients at once in a single loaded job.

Frequently asked questions

Related guides

References

• GitHub Actions documentation