karatelabs/karate · error · DriverException

waitUntil timeout

Error message

waitUntil timeout: ${expression}

What it means

W3cDriver.waitUntil(expression) repeatedly evaluates a page-level JS expression (exceptions ignored each poll) until it returns truthy or the timeout elapses. If never truthy, a DriverException with the expression text is thrown. This variant is not scoped to an element.

Solutions

1. Evaluate the expression via driver.script() once and inspect the actual value/error
2. Increase the timeout via waitUntil(expression, timeout)
3. Fix expression syntax — poll exceptions are silently ignored, so a broken expression just times out
4. Add an alternate condition (e.g. also detect the failure state) instead of only the success state

Example fix

// before
driver.waitUntil("window.appReady === true"); // appReady never set, script failed
// after
String ready = driver.script("window.appReady === true");
// inspect ready, fix app bootstrap or use: driver.waitUntil("window.app && window.appReady === true", 30000)

Object v = driver.script(expression); // evaluate once; check value/errors first

try {
    driver.waitUntil(expression, timeout);
} catch (DriverException e) {
    // run driver.script(expression) once to see the real value or JS error
}

When it happens

Trigger: Calling driver.waitUntil(jsExpression) (or with explicit timeout) where the expression never evaluates truthy — e.g. waiting on window state, a JS variable, or document.readyState condition that never occurs.

Common situations: Waiting on a global JS variable the app never sets (script blocked/failed); expression syntax error so every poll throws and is swallowed; waiting for XHR completion flag that is only set on success while the request failed.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• waitUntil timeout: expression
• waitFor timeout
• waitForAny timeout
• waitForText timeout: expected
• waitForEnabled timeout

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/w3c/W3cDriver.java:659

    public boolean waitUntil(String expression) {
        return waitUntil(expression, options.getTimeoutDuration());
    }

    @Override
    public boolean waitUntil(String expression, java.time.Duration timeout) {
        long deadline = System.currentTimeMillis() + timeout.toMillis();
        while (System.currentTimeMillis() < deadline) {
            try {
                Object result = eval(expression);
                if (isTruthy(result)) {
                    return true;
                }
            } catch (Exception e) {
                // Ignore
            }
            sleep(options.getRetryInterval());
        }
        throw new DriverException("waitUntil timeout: " + expression);
    }

    @Override
    public Object waitUntil(java.util.function.Supplier<Object> condition) {
        return waitUntil(condition, options.getTimeoutDuration());
    }

    @Override
    public Object waitUntil(java.util.function.Supplier<Object> condition, java.time.Duration timeout) {
        long deadline = System.currentTimeMillis() + timeout.toMillis();
        while (System.currentTimeMillis() < deadline) {
            Object result = condition.get();
            if (isTruthy(result)) {
                return result;
            }
            sleep(options.getRetryInterval());
        }
        throw new DriverException("waitUntil (supplier) timeout");

View on GitHub (pinned to a22eb90246)