karatelabs/karate · error · DriverException

WebDriver " + request.method() + " " +…

Error message

WebDriver " + request.method() + " " + request.uri().getPath() + " failed (" + response.statusCode() + "): " + message

What it means

This DriverException is thrown when a WebDriver command executed over HTTP returns a non-success status code. W3cSession.execute() parses the WebDriver error payload and prefixes the message with the failing HTTP method, endpoint path and status code, so the developer sees exactly which remote command failed and the driver-reported reason.

Solutions

Read the driver-reported message after the status code — it names the concrete WebDriver error (e.g. stale element reference, no such window) and fix the root cause
Re-locate the element before interacting if the error is stale-element
Check that the chromedriver/geckodriver version matches the installed browser version
Add appropriate implicit/explicit wait before the failing command

Example fix

// before
driver.locate("#item").click(); // fails after DOM re-render
// after
driver.waitFor("#item").click();

Defensive patterns

Strategy: try-catch

Validate before calling

// before calling any driver command, ensure session is alive
if (session == null || !session.isAlive()) {
    session = new W3cSession(options);
}

Try / catch

try {
    Object res = session.get(url);
} catch (DriverException e) {
    // message contains method, path, status and driver-reported reason
    if (e.getMessage().contains("stale element reference")) {
        element = driver.waitFor(selector);
    } else {
        throw e;
    }
}

Prevention

Use explicit waits before interacting with elements
Re-locate elements after DOM mutations
Keep driver version matched to browser version
Wrap remote commands in retry logic for transient failures

When it happens

Trigger: Any get(), postRaw() or delete() call on a W3cSession whose HTTP response status is not success — e.g. clicking a stale element, switching to a closed window, or a command the driver endpoint does not support. Server-side error maps may include 'error' and 'message' keys which are merged into the thrown message.

Common situations: Stale element references after DOM updates, timeouts during navigation, invalid selectors, interacting with a browser session that crashed or was closed, or hitting an endpoint unsupported by the browser/driver version in use.

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/2c1ee0c5e12f69c6. Report an issue: GitHub.

Appendix: source

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

                java.util.HashMap<String, Object> nullResult = new java.util.HashMap<>();
                nullResult.put("value", null);
                return nullResult;
            }
            Map<String, Object> result = Json.of(body).asMap();

            // Check for W3C error response
            if (response.statusCode() >= 400) {
                Object value = result.get("value");
                String message = "WebDriver error";
                if (value instanceof Map) {
                    Map<String, Object> errorMap = (Map<String, Object>) value;
                    message = (String) errorMap.getOrDefault("message", message);
                    String error = (String) errorMap.get("error");
                    if (error != null) {
                        message = error + ": " + message;
                    }
                }
                throw new DriverException("WebDriver " + request.method() + " "
                        + request.uri().getPath() + " failed (" + response.statusCode() + "): " + message);
            }

            return result;
        } catch (DriverException e) {
            throw e;
        } catch (IOException | InterruptedException e) {
            if (e instanceof InterruptedException) {
                Thread.currentThread().interrupt();
            }
            throw new DriverException("WebDriver request failed: " + request.method() + " "
                    + request.uri() + ": " + e.getMessage(), e);
        }
    }

    private static Object getValue(Map<String, Object> response) {
        return response.get("value");
    }

View on GitHub (pinned to a22eb90246)