karatelabs/karate · error · DriverException

element not found:

Error message

element not found: 

What it means

BaseElement.assertExists() guards all element-content accessors (text, html, innerHtml, value, attribute, property). When the element does not exist in the DOM (exists == false), reading it throws this DriverException carrying the original locator. Karate fails fast instead of returning null/empty so the scenario stops at the real cause: the element was not there.

Solutions

1. Wait for the element before reading: use driver.waitFor("#id") or waitForText/location before calling accessors
2. Verify the locator (open the page devtools and test the CSS/XPath); fix typos and stale selectors
3. If absence is legitimate, use the optional variant (e.g. driver.optional(locator)) and check exists() before reading

Example fix

// before
String txt = driver.locate("#result").text();
// after
driver.waitFor("#result");
String txt = driver.locate("#result").text();

// in Karate script, before reading:
// waitFor('#result') first; or use driver.optional('#result') and check exists()

// if (driver.optional('#result').exists()) { /* safe to read */ }

try { String t = el.text(); } catch (DriverException e) { if (e.getMessage().startsWith("element not found")) { /* handle absence */ } else throw e; }

When it happens

Trigger: Calling el.text() / el.html() / el.value() etc. on an Element returned by a lookup that failed to find the node — e.g. after driver.locate("#missing"), or where a prior wait timed out and the stale Element handle is used.

Common situations: Wrong or outdated selector (CSS/XPath typo); element rendered only under certain conditions (modal, lazy load, auth state); race conditions where the script reads before the SPA renders; iframe/switch context misses.

Related errors

• KARATE_ELEMENT_NOT_FOUND
• driver keyword requires a URL argument
• driver URL evaluated to null:
• missing array argument 'patterns':
• missing 'mock' or 'handler' in intercept config

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/BaseElement.java:383

                    }
                }
                return inputFile(files.toArray(new String[0]));
            };
            case "attribute" -> (JavaCallable) (ctx, args) -> attribute(args.length > 0 ? String.valueOf(args[0]) : "");
            case "property" -> (JavaCallable) (ctx, args) -> property(args.length > 0 ? String.valueOf(args[0]) : "");
            case "script" -> (JavaCallable) (ctx, args) -> script(args.length > 0 ? String.valueOf(args[0]) : "");
            // Navigation — selector-based, the W3C DOM Element idioms.
            case "closest" -> (JavaCallable) (ctx, args) -> closest(args.length > 0 ? String.valueOf(args[0]) : "");
            case "matches" -> (JavaCallable) (ctx, args) -> matches(args.length > 0 ? String.valueOf(args[0]) : "");
            default -> null;
        };
    }

    // ========== Utilities ==========

    protected void assertExists() {
        if (!exists) {
            throw new DriverException("element not found: " + locator);
        }
    }

    @Override
    public String toString() {
        return "Element[" + locator + ", exists=" + exists + "]";
    }

    // ========== Retry Element ==========

    private static class RetryElement extends BaseElement {
        private final Integer retryCount;
        private final Integer retryInterval;

        RetryElement(Driver driver, String locator, boolean exists) {
            super(driver, locator, exists);
            this.retryCount = null;
            this.retryInterval = null;

View on GitHub (pinned to a22eb90246)