karatelabs/karate · error · DriverException

WebDriver session create failed: " + e.getMessage()

Error message

WebDriver session create failed: " + e.getMessage()

What it means

W3cSession.create wraps IOException/InterruptedException from the HTTP exchange in a DriverException 'WebDriver session create failed: <cause message>'. This is the transport-level failure path: the request to the WebDriver server could not be completed at all (connection refused, reset, or the thread was interrupted).

Solutions

  1. Check the wrapped cause (e.getMessage / getCause) — 'Connection refused' means nothing is listening on host:port
  2. Verify the WebDriver server is running and reachable (curl http://host:port/status)
  3. Correct the host/port configuration or restart the driver binary
  4. If InterruptedException, avoid interrupting driver startup threads and check for premature framework shutdown

Example fix

// before
Map<String, Object> opts = MapUtils.of("type", "chromedriver", "port", 9515, "host", "10.0.0.99"); // grid down
// after
Map<String, Object> opts = MapUtils.of("type", "chromedriver", "port", 9515, "host", "localhost");
// and pre-check: curl http://localhost:9515/status before starting the session
Defensive patterns

Strategy: retry

Validate before calling

// reachability probe before session create
try (Socket s = new Socket(host, port)) { /* endpoint listening */ } catch (IOException e) { /* abort or restart driver */ }

Try / catch

try {
    session = W3cSession.create(client, baseUrl, caps, timeout);
} catch (DriverException e) {
    if (e.getCause() instanceof IOException) {
        // restart driver binary / fix host:port, then retry with backoff
    }
}

Prevention

When it happens

Trigger: POST /session fails at the network layer — driver process died between startup and session creation, wrong host/port, TLS/proxy issues, or the waiting thread was interrupted while blocked on client.send().

Common situations: Driver crashed right after startup (check driver logs); firewall blocking the port; connecting to a remote grid that is down; test harness shutting down and interrupting the driver-start thread.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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

Appendix: source

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

            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);
        }
    }

    // ========== Navigation ==========

    public void navigateTo(String url) {
        post("url", Map.of("url", url));
    }

    public String getUrl() {
        return (String) getValue(get("url"));
    }

    public String getTitle() {
        return (String) getValue(get("title"));
    }

    public void back() {

View on GitHub (pinned to a22eb90246)