karatelabs/karate · error · DriverException

timeout waiting for element

Error message

timeout waiting for element: ${locator}

What it means

driver.waitFor(locator, timeout) polls until exists(locator) is true, using the given timeout and the configured retry interval. If the element never appears within the timeout, Karate throws this DriverException instead of returning an Element.

Solutions

1. Validate the selector against the app state at that point; fix typos/stale ids.
2. Increase the timeout Duration to cover worst-case load times.
3. Ensure prerequisite steps (navigation, login, opening the modal) complete before waiting.
4. Switch to the containing iframe before waiting if the element is inside one; catch DriverException to fail with a custom diagnostic.

Example fix

// before
Element e = driver.waitFor('#results', Duration.ofSeconds(2)); // too short
// after
Element e = driver.waitFor('#results', Duration.ofSeconds(30));

// ensure prerequisites are done before waiting
if (!driver.exists("#container")) throw new IllegalStateException("page not ready");

try {
    Element e = driver.waitFor(locator, Duration.ofSeconds(30));
} catch (Exception e) {
    if (e.getMessage().startsWith("timeout waiting for element")) {
        throw new AssertionError("element never appeared within timeout: " + locator, e);
    } else throw e;
}

When it happens

Trigger: driver.waitFor(locator, Duration) where the element does not appear within the explicit timeout: wrong selector, element behind an unperformed interaction, element in another frame, or timeout too short for the app's load time.

Common situations: Fixed timeout too aggressive on slow CI or cold-started pages; waiting for content that requires login/data setup that did not happen; element appears in a modal that was never opened; selector broken after a UI refactor.

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

• element not found after
• timeout waiting for any element
• timeout waiting for text
• timeout waiting for element to be enabled
• timeout waiting for elements

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

Appendix: source

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

    }

    // ========== Wait Methods ==========

    /**
     * Wait for an element to exist.
     */
    public Element waitFor(String locator) {
        return waitFor(locator, options.getTimeoutDuration());
    }

    /**
     * Wait for an element to exist with custom timeout.
     */
    public Element waitFor(String locator, Duration timeout) {
        Element found = pollFor(timeout.toMillis(), options.getRetryInterval(),
                () -> exists(locator) ? BaseElement.existing(this, locator) : null);
        if (found == null) {
            throw new DriverException("timeout waiting for element: " + locator);
        }
        return found;
    }

    /**
     * Wait for any of the locators to match.
     */
    public Element waitForAny(String locator1, String locator2) {
        return waitForAny(new String[]{locator1, locator2});
    }

    /**
     * Wait for any of the locators to match.
     */
    public Element waitForAny(String[] locators) {
        return waitForAny(locators, options.getTimeoutDuration());
    }

View on GitHub (pinned to a22eb90246)