timeout waiting for frame context: frameId=

Error message

timeout waiting for frame context: frameId={} (will retry on first use)

What it means

For same-origin frames, CdpDriver polls (1s bound) the frame's execution context with a trivial Runtime.evaluate ("typeof document !== 'undefined'") to confirm it can run JS. If the context is not confirmed ready within the bound, this warning is logged. It is deliberately non-fatal — script()'s retry logic handles the remainder on first use.

Solutions

Let the built-in retry handle it (usually sufficient); if not, add an explicit waitFor on an element inside the frame after switchFrame.
Increase retryInterval in driver options to widen the effective first-use retry window.
Avoid switching frames during heavy navigation; wait for load events first.
Reload or re-attach if the context is persistently unready (stale context id).

Example fix

// before
driver.switchFrame("iframe#app");
String html = driver.script("document", "document.body.innerHTML");
// after
driver.switchFrame("iframe#app");
driver.waitFor("body");
String html = driver.script("document", "document.body.innerHTML");

Defensive patterns

Strategy: retry

Validate before calling

driver.waitFor("iframe#app");
driver.switchFrame("iframe#app");
driver.waitFor("body"); // ensure document exists before script()

Try / catch

try {
    Object v = driver.script("document", expr);
} catch (RuntimeException e) {
    // context may still be warming: brief sleep + one retry
    sleep(500);
    Object v = driver.script("document", expr);
}

Prevention

Wait for an element in the frame before evaluating JS
Increase driver retryInterval for slow environments
Don't switch frames during active navigation

When it happens

Trigger: switchFrame() followed immediately by evaluation while the frame's document is still loading, the contextId exists but the document isn't ready, or repeated eval errors during the 1s poll.

Common situations: Very large or slow-loading iframes, switching frames right after a navigation triggers new context creation, or CI machines slow enough that 1s of polling isn't enough.

Understand the failure class

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

Related errors

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

Appendix: source

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

            try {
                CdpResponse response = cdp.method("Runtime.evaluate")
                        .param("expression", "typeof document !== 'undefined'")
                        .param("returnByValue", true)
                        .param("contextId", contextId)
                        .send();
                if (!response.isError() && Boolean.TRUE.equals(response.getResult("result.value"))) {
                    logger.trace("frame context ready: frameId={}, contextId={}", frameId, contextId);
                    return true;
                }
            } catch (Exception e) {
                // Context not ready yet, will retry
                logger.trace("frame context not ready yet: {}", e.getMessage());
            }
            return false;
        });
        if (!ready) {
            // Timeout is not fatal - retry logic in script() will handle it
            logger.warn("timeout waiting for frame context: frameId={} (will retry on first use)", frameId);
        }
    }

    // ========== Lifecycle ==========

    /**
     * Close driver and browser.
     */
    public void quit() {
        if (terminated) {
            return;
        }
        terminated = true;
        ACTIVE.remove(this);

        logger.debug("quitting CDP driver");

        // Unblock anyone awaiting readiness (e.g. a script() racing this quit) - once

View on GitHub (pinned to a22eb90246)