karatelabs/karate · error · DriverException

waitForUrl timeout: expected URL containing

Error message

waitForUrl timeout: expected URL containing: ${expected}

What it means

W3cDriver.waitForUrl polls getUrl() every retry interval and returns as soon as the current URL contains the expected substring; if the URL never contains it within the timeout, a DriverException with the expected substring is thrown.

Solutions

1. Log driver.getUrl() after the action and compare with the expected substring
2. Increase the timeout via waitForUrl(expected, timeout)
3. Fix the expected substring to match the real URL scheme/host/path exactly
4. Verify the triggering action succeeded (check for error UI) before waiting on the URL

Example fix

// before
driver.waitForUrl('/dashboard'); // app actually lands on '/home'
// after
driver.waitForUrl('/home', 15000);

if (driver.getUrl().contains(expected)) { /* already navigated */ }

try {
    driver.waitForUrl(expected, timeout);
} catch (DriverException e) {
    // log driver.getUrl() and current page title to diagnose failed navigation
}

When it happens

Trigger: Calling driver.waitForUrl(expected) after navigation-triggering actions (login, redirect) when the browser URL never contains the expected substring within the timeout — e.g. navigation never happened, redirect failed, or expected substring is wrong (trailing slash, http vs https, query params).

Common situations: Login rejected so no redirect occurs; expected URL uses a different base path or environment hostname; SPA changes route via hash while code expects a path substring; slow SSO redirect exceeding the timeout.

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 URL to contain
• page load timeout after
• waitFor timeout
• waitForAny timeout
• waitForText timeout: expected

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

Appendix: source

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

        throw new DriverException("waitForEnabled timeout: " + locator);
    }

    @Override
    public String waitForUrl(String expected) {
        return waitForUrl(expected, options.getTimeoutDuration());
    }

    @Override
    public String waitForUrl(String expected, java.time.Duration timeout) {
        long deadline = System.currentTimeMillis() + timeout.toMillis();
        while (System.currentTimeMillis() < deadline) {
            String url = getUrl();
            if (url != null && url.contains(expected)) {
                return url;
            }
            sleep(options.getRetryInterval());
        }
        throw new DriverException("waitForUrl timeout: expected URL containing: " + expected);
    }

    @Override
    public Element waitUntil(String locator, String expression) {
        return waitUntil(locator, expression, options.getTimeoutDuration());
    }

    @Override
    public Element waitUntil(String locator, String expression, java.time.Duration timeout) {
        long deadline = System.currentTimeMillis() + timeout.toMillis();
        String js = Locators.scriptSelector(locator, expression);
        while (System.currentTimeMillis() < deadline) {
            try {
                Object result = eval(js);
                if (isTruthy(result)) {
                    return BaseElement.existing(this, locator);
                }
            } catch (Exception e) {

View on GitHub (pinned to a22eb90246)