karatelabs/karate · error · DriverException

WebDriver session create failed with status " +…

Error message

WebDriver session create failed with status " + response.statusCode() + ": " + response.body()

What it means

W3cSession.create posts the new-session payload to the WebDriver endpoint and throws DriverException when the HTTP response status is not 200, embedding the status code and response body. This surfaces driver-side rejections of session creation (bad capabilities, unsupported browser, driver not running correctly).

Solutions

  1. Read the response body in the message — WebDriver errors explain the rejected capability or missing binary
  2. Update the browser and driver to matching versions (chromedriver ↔ Chrome, geckodriver ↔ Firefox)
  3. Verify the capabilities/options being sent are valid W3C session capabilities
  4. Confirm the WebDriver endpoint URL and that the server responds to /status

Example fix

// before
Map<String, Object> opts = MapUtils.of("type", "chromedriver", "chromedriverPath", "/old/path/chromedriver");
// after — matching driver version
Map<String, Object> opts = MapUtils.of("type", "chromedriver", "chromedriverPath", "/usr/local/bin/chromedriver");
// and align installed Chrome version with the driver version
Defensive patterns

Strategy: retry

Validate before calling

// pre-check the WebDriver endpoint
HttpRequest req = HttpRequest.newBuilder(URI.create(baseUrl + "/status")).GET().build();
// require HTTP 200 and value.ready == true before creating a session

Try / catch

try {
    session = W3cSession.create(client, baseUrl, caps, timeout);
} catch (DriverException e) {
    // message includes HTTP status + body: fix capabilities or versions, then retry
}

Prevention

When it happens

Trigger: POST /session to the WebDriver server returns 4xx/5xx — mismatched or invalid capabilities JSON, unsupported browser version, driver bound to a different browser path, or malformed W3C payload.

Common situations: chromedriver older than the installed Chrome (capabilities rejected); wrong w3c capabilities keys; connecting to a grid that rejects the requested platform; driver process is up but its browser binary path is wrong.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/w3c/W3cSession.java:112

        HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
                .uri(uri)
                .header("Content-Type", "application/json; charset=utf-8")
                .timeout(timeout);

        String userInfo = uri.getUserInfo();
        if (userInfo != null && !userInfo.isBlank()) {
            String basicAuth = "Basic " + Base64.getEncoder().encodeToString(userInfo.getBytes());
            requestBuilder.header("Authorization", basicAuth);
        }

        HttpRequest request = requestBuilder
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            if (response.statusCode() != 200) {
                throw new DriverException("WebDriver session create failed with status "
                        + response.statusCode() + ": " + response.body());
            }

            Map<String, Object> body = Json.of(response.body()).asMap();
            Map<String, Object> value = (Map<String, Object>) body.get("value");
            String sessionId = (String) value.get("sessionId");
            if (sessionId == null) {
                throw new DriverException("WebDriver session create response missing sessionId: " + response.body());
            }

            logger.info("W3C session created: {}", sessionId);
            return new W3cSession(client, baseUrl, sessionId, timeout);
        } catch (IOException | InterruptedException e) {
            if (e instanceof InterruptedException) {
                Thread.currentThread().interrupt();
            }
            throw new DriverException("WebDriver session create failed: " + e.getMessage(), e);
        }

View on GitHub (pinned to a22eb90246)