{"record":{"id":"a3e9dda78ed98911","repo":"karatelabs/karate","slug":"failed-to-start-executable-message","errorCode":null,"errorMessage":"Failed to start ${executable}: ${message}","messagePattern":"Failed to start (.+?): (.+?)","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"critical","filePath":"karate-core/src/main/java/io/karatelabs/driver/w3c/W3cDriver.java","lineNumber":154,"sourceCode":"        ProcessHandle process = ProcessHandle.start(\n                ProcessBuilder.create()\n                        .args(command)\n                        .redirectErrorStream(true)\n                        .logToContext(false) // don't pollute scenario logs with driver chatter\n                        .build()\n        );\n\n        try {\n            // Wait for the driver to start accepting connections\n            waitForPort(\"localhost\", port, opts.getTimeoutDuration().toMillis());\n            logger.info(\"{} started on port {}\", executable, port);\n\n            String baseUrl = \"http://localhost:\" + port;\n            W3cSession session = W3cSession.create(baseUrl, opts.buildSessionPayload(), opts.getTimeoutDuration());\n            return new W3cDriver(session, opts, process);\n        } catch (RuntimeException e) {\n            process.close(true);\n            throw new DriverException(\"Failed to start \" + executable + \": \" + e.getMessage(), e);\n        }\n    }\n\n    /**\n     * Get the underlying W3C session for direct protocol access.\n     */\n    public W3cSession getSession() {\n        return session;\n    }\n\n    // ========== CoreDriver Tier 1: Essential Primitives ==========\n\n    /**\n     * Execute JavaScript via W3C executeScript.\n     *\n     * <p>Battle-tested pattern from v1 WebDriver: if JS execution fails, sleep once and\n     * retry before throwing. This handles transient failures that occur when the page is\n     * still loading or transitioning. The v1 codebase proved this single-retry approach","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/driver/w3c/W3cDriver.java#L136-L172","documentation":"W3cDriver.launch starts the WebDriver process (e.g. chromedriver/geckodriver), then creates a W3C session over HTTP. Any RuntimeException during process start or session creation is wrapped into a DriverException 'Failed to start <executable>: <message>' after killing the process, preserving the underlying cause.","triggerScenarios":"WebDriver binary missing or not executable; driver process starts but the session endpoint never becomes reachable; session creation POST fails (bad capabilities, protocol mismatch, port already in use); timeout while waiting for the local server.","commonSituations":"chromedriver version mismatched with installed Chrome; another process holding the chosen port; running chromedriver binary for the wrong OS/arch; missing browser on CI; wrong 'executable' path in config.","solutions":["Read the wrapped cause (e.getMessage()) — it names the actual failure","Verify the configured executable runs: `<executable> --version` and matches the installed browser version","Check the port is free or let the driver pick a free port","Confirm the target browser is installed and reachable","Increase the timeout if the driver binary is slow to boot on CI"],"exampleFix":"// before: mismatched driver/browser\ngeckodriver 0.30 with very new Firefox\n// after\nupgrade geckodriver to a version matching the installed Firefox","handlingStrategy":"try-catch","validationCode":"String v = new ProcessBuilder(executable, \"--version\").start().getText().trim();\n// compare against installed browser version before launching","typeGuard":null,"tryCatchPattern":"try {\n    W3cDriver d = W3cDriver.start(opts);\n} catch (DriverException e) {\n    logger.error(\"driver launch failed: {} cause: {}\", e.getMessage(), e.getCause());\n    // fix per cause: version mismatch, busy port, missing browser\n}","preventionTips":["Keep WebDriver binary version matched to browser version (use webdriver-manager style tooling)","Validate the executable path exists and is runnable before launch","Let the driver choose a free port instead of hardcoding one","Install the browser itself in CI images, not just the driver"],"tags":["webdriver","browser-launch","process","driver-mismatch"],"backgroundTag":"module-init-failed","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"}