{"record":{"id":"a227e7cd5431d145","repo":"karatelabs/karate","slug":"timeout-waiting-for-webdriver-on-host-port","errorCode":null,"errorMessage":"Timeout waiting for WebDriver on ${host}:${port}","messagePattern":"Timeout waiting for WebDriver on (.+?):(.+?)","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/driver/w3c/W3cDriver.java","lineNumber":1195,"sourceCode":"\n    private static void sleep(int millis) {\n        try {\n            Thread.sleep(millis);\n        } catch (InterruptedException e) {\n            Thread.currentThread().interrupt();\n        }\n    }\n\n    private static void waitForPort(String host, int port, long timeoutMillis) {\n        long deadline = System.currentTimeMillis() + timeoutMillis;\n        while (System.currentTimeMillis() < deadline) {\n            try (Socket socket = new Socket(host, port)) {\n                return; // Port is open\n            } catch (IOException e) {\n                sleep(200);\n            }\n        }\n        throw new DriverException(\"Timeout waiting for WebDriver on \" + host + \":\" + port);\n    }\n\n    // ========== W3C Dialog ==========\n\n    private static class W3cDialog implements Dialog {\n        private final W3cSession session;\n        private final String text;\n        private boolean handled = false;\n\n        W3cDialog(W3cSession session, String text) {\n            this.session = session;\n            this.text = text;\n        }\n\n        @Override\n        public String getMessage() {\n            return text;\n        }","sourceCodeStart":1177,"sourceCodeEnd":1213,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/driver/w3c/W3cDriver.java#L1177-L1213","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the driver binary exists, is executable, and matches the platform/browsers, and that it is on PATH or configured via config path","Increase the startup `timeout` in driver options for slow environments","Check for port conflicts and firewall/proxy rules blocking the driver port; kill stale driver processes","If using a remote driver, confirm host/port point at the running WebDriver endpoint (curl the /status endpoint)"],"exampleFix":"// before\nMap<String, Object> opts = MapUtils.of(\"type\", \"chromedriver\");\n// after — allow more time and pin the binary\nMap<String, Object> opts = MapUtils.of(\"type\", \"chromedriver\", \"timeout\", 60000,\n        \"chromedriverPath\", \"/usr/local/bin/chromedriver\");","handlingStrategy":"retry","validationCode":"// probe the driver port before creating a session\ntry (Socket s = new Socket(host, port)) { /* driver is up */ } catch (IOException e) { /* wait/retry */ }","typeGuard":null,"tryCatchPattern":"try {\n    driver = DriverOptions.startDriverAndDriverSession(opts, null);\n} catch (Exception e) {\n    if (e.getMessage().startsWith(\"Timeout waiting for WebDriver\")) {\n        // check driver binary/logs, then retry with a larger timeout\n    }\n}","preventionTips":["Verify driver binary presence/executability on every CI image","Give generous startup timeouts in containers","Monitor for stale driver processes holding ports"],"tags":["webdriver","startup","timeout","connection"],"backgroundTag":"request-timeout","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}