karatelabs/karate · error · DriverException

Timeout waiting for WebDriver on

Error message

Timeout waiting for WebDriver on ${host}:${port}

What it means

W3cDriver polls the WebDriver server's host:port with TCP sockets at startup and throws DriverException 'Timeout waiting for WebDriver on host:port' if the port never opens within the configured deadline. It means the driver binary never became reachable, so no WebDriver commands can be sent.

Solutions

1. Verify the driver binary exists, is executable, and matches the platform/browsers, and that it is on PATH or configured via config path
2. Increase the startup `timeout` in driver options for slow environments
3. Check for port conflicts and firewall/proxy rules blocking the driver port; kill stale driver processes
4. If using a remote driver, confirm host/port point at the running WebDriver endpoint (curl the /status endpoint)

Example fix

// before
Map<String, Object> opts = MapUtils.of("type", "chromedriver");
// after — allow more time and pin the binary
Map<String, Object> opts = MapUtils.of("type", "chromedriver", "timeout", 60000,
        "chromedriverPath", "/usr/local/bin/chromedriver");

// probe the driver port before creating a session
try (Socket s = new Socket(host, port)) { /* driver is up */ } catch (IOException e) { /* wait/retry */ }

try {
    driver = DriverOptions.startDriverAndDriverSession(opts, null);
} catch (Exception e) {
    if (e.getMessage().startsWith("Timeout waiting for WebDriver")) {
        // check driver binary/logs, then retry with a larger timeout
    }
}

When it happens

Trigger: Starting a W3cDriver session where the driver process (chromedriver/geckodriver etc.) fails to launch, crashes immediately, listens on a different port/interface, or is slower than the startup timeout.

Common situations: Driver executable missing or wrong architecture (fails silently at spawn); port already taken by a stale process or blocked by firewall; slow CI container exceeding the default timeout; wrong host configured when connecting to a remote/grid driver.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Port : not available within timeout
• waitFor timeout
• waitForAny timeout
• waitForText timeout: expected
• waitForEnabled timeout

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/a227e7cd5431d145. Report an issue: GitHub.

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/w3c/W3cDriver.java:1195

    private static void sleep(int millis) {
        try {
            Thread.sleep(millis);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    private static void waitForPort(String host, int port, long timeoutMillis) {
        long deadline = System.currentTimeMillis() + timeoutMillis;
        while (System.currentTimeMillis() < deadline) {
            try (Socket socket = new Socket(host, port)) {
                return; // Port is open
            } catch (IOException e) {
                sleep(200);
            }
        }
        throw new DriverException("Timeout waiting for WebDriver on " + host + ":" + port);
    }

    // ========== W3C Dialog ==========

    private static class W3cDialog implements Dialog {
        private final W3cSession session;
        private final String text;
        private boolean handled = false;

        W3cDialog(W3cSession session, String text) {
            this.session = session;
            this.text = text;
        }

        @Override
        public String getMessage() {
            return text;
        }

View on GitHub (pinned to a22eb90246)