karatelabs/karate · error · DriverException

timeout waiting for condition

Error message

timeout waiting for condition: ${expression}

What it means

CdpDriver.waitUntil(expression, timeout) polls a page-level JavaScript expression until it is truthy; if the poll budget expires it throws a DriverException with the expression text. Unlike the element variant, no locator is involved — the failure means the page state itself never satisfied the expression.

Solutions

1. Run the expression manually in browser devtools on the failing page to check its value and syntax
2. Harden the expression against undefined intermediate objects (optional chaining)
3. Increase the timeout duration
4. Ensure prior steps actually trigger the state the expression watches

Example fix

// before
driver.waitUntil("window.config.loaded", Duration.ofSeconds(5));
// after
driver.waitUntil("window.config?.loaded === true", Duration.ofSeconds(15));

// evaluate once and log before polling
Object val = driver.script("window.config?.loaded === true");
logger.debug("initial condition value={}", val);

try {
    driver.waitUntil("window.config?.loaded === true", Duration.ofSeconds(20));
} catch (DriverException e) {
    logger.error("page condition never truthy; val={}", driver.script("window.config?.loaded"));
    throw e;
}

When it happens

Trigger: driver.waitUntil("window.appReady === true", duration) or a JS boolean condition that never becomes true — the script throws in-page each poll, returns undefined/false, or the timeout is too short.

Common situations: Waiting on a global flag the app sets only under conditions the test never triggers; JS runtime error inside the expression (accessing property of undefined); SPA hydration slower than the wait on CI; page navigated away so the expression evaluates in the wrong context.

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

• timeout waiting for condition
• timeout waiting for condition
• element not found after
• karate.driver can only be read within a scenario
• retry FAILED after attempts: |

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/cdp/CdpDriver.java:3430

        }
        return found;
    }

    /**
     * Wait until a JavaScript expression evaluates to truthy.
     */
    public boolean waitUntil(String expression) {
        return waitUntil(expression, options.getTimeoutDuration());
    }

    /**
     * Wait until a JavaScript expression evaluates to truthy with custom timeout.
     */
    public boolean waitUntil(String expression, Duration timeout) {
        boolean met = pollUntil(timeout.toMillis(), options.getRetryInterval(),
                () -> Terms.isTruthy(script(expression)));
        if (!met) {
            throw new DriverException("timeout waiting for condition: " + expression);
        }
        return true;
    }

    /**
     * Wait until a supplier returns a truthy value.
     */
    public Object waitUntil(Supplier<Object> condition) {
        return waitUntil(condition, options.getTimeoutDuration());
    }

    /**
     * Wait until a supplier returns a truthy value with custom timeout.
     */
    public Object waitUntil(Supplier<Object> condition, Duration timeout) {
        Object result = pollFor(timeout.toMillis(), options.getRetryInterval(), () -> {
            Object r = condition.get();
            return Terms.isTruthy(r) ? r : null;

View on GitHub (pinned to a22eb90246)