karatelabs/karate · error · DriverException

waitForEnabled timeout

Error message

waitForEnabled timeout: ${locator}

What it means

W3cDriver.waitForEnabled polls the element's enabled state every retry interval, swallowing per-poll exceptions since the element may not exist yet. If the element never becomes enabled within the timeout, a DriverException naming the locator is thrown.

Solutions

1. Inspect the element in devtools to see why it remains disabled (attribute/state)
2. Complete the precondition that enables it (fill required fields, trigger validation) before waiting
3. Increase the timeout via waitForEnabled(locator, timeout)
4. If the element should never enable, adjust the test expectation instead of waiting

Example fix

// before
driver.waitForEnabled('#submit'); // disabled until terms checkbox checked
// after
driver.click('#accept-terms');
driver.waitForEnabled('#submit');

if (driver.exists(locator) && driver.enabled(locator)) { /* already enabled */ }

try {
    driver.waitForEnabled(locator, timeout);
} catch (DriverException e) {
    // element stayed disabled; log DOM state of the element
}

When it happens

Trigger: Calling driver.waitForEnabled(locator) on an element that stays disabled (HTML disabled attribute, form invalid, other field pending) or never appears at all within the timeout.

Common situations: Button disabled because a form fails HTML5 validation; disabled until an async validation completes slower than the timeout; element is permanently disabled in the app (test assumption wrong); selector points at a wrapper rather than the input.

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

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

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

Appendix: source

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

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

    @Override
    public Element waitForEnabled(String locator, java.time.Duration timeout) {
        long deadline = System.currentTimeMillis() + timeout.toMillis();
        while (System.currentTimeMillis() < deadline) {
            try {
                if (enabled(locator)) {
                    return BaseElement.existing(this, locator);
                }
            } catch (Exception e) {
                // Element may not exist yet
            }
            sleep(options.getRetryInterval());
        }
        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);

View on GitHub (pinned to a22eb90246)