WebdriverIO "ECONNREFUSED 127.0.0.1:4444" connecting to the driver in CI

By Daniel Zoghalchali·Latchkey

When wdio is configured to talk to a remote WebDriver server (Selenium standalone or a Grid hub) on port 4444, ECONNREFUSED means nothing is listening there yet. The server is not started, not ready, or on a different host.

What this error means

wdio fails to start sessions with "Error: connect ECONNREFUSED 127.0.0.1:4444" while using a hostname/port config that points at a standalone server or hub.

ERROR webdriver: Request failed with status undefined due to
Error: connect ECONNREFUSED 127.0.0.1:4444
ERROR @wdio/local-runner: Failed launching session

Common causes

The WebDriver server is not running

The config sets hostname/port to a Selenium standalone or Grid that the job never started, so the connection is refused.

The test connected before the server was ready

The server container started but had not finished binding to 4444 when wdio tried to connect.

How to fix it

Start the server and wait for it before wdio

1. Start the Selenium standalone or Grid service in CI.
2. Wait until port 4444 answers before launching wdio.
3. Re-run so the session connects to a ready server.

services:
  selenium:
    image: selenium/standalone-chrome:4.21.0
    ports: ['4444:4444']
# then, before wdio:
- run: |
    for i in $(seq 1 30); do
      curl -sf http://localhost:4444/status && break || sleep 2
    done

Or run wdio locally without a remote server

If you do not need a standalone server, remove hostname/port so wdio drives the local driver directly instead of dialing 4444.

// wdio.conf.js: omit hostname/port for the local runner
exports.config = { runner: 'local', capabilities: [{ browserName: 'chrome' }] }

How to prevent it

• Poll /status on port 4444 before connecting to a standalone server or hub.
• Use the local runner when no remote WebDriver server is needed.
• Match the configured hostname/port to where the server actually listens.

Frequently asked questions

Related guides

References

• GitHub Actions documentation