karatelabs/karate · error · DriverException

no element found matching

Error message

no element found {positionDescription} {referenceLocator} matching: {locator}

What it means

Thrown by Finder.find when no element matching the locator exists within the reference element's positional scope (e.g. right of / below / within the reference). findAll returned an empty list, so find fails rather than returning null.

Solutions

Wait for the element to appear before finding (waitFor on the composed locator)
Use findAll and check for an empty list when absence is acceptable
Verify the reference element and positional constraint match the actual DOM
Inspect the page DOM (script document.body.innerHTML) to confirm the structure

Example fix

// before
Element label = input("#email").find("tag:label");
// after
List<Element> labels = input("#email").findAll("tag:label");
if (!labels.isEmpty()) { Element label = labels.get(0); ... }

Defensive patterns

Strategy: try-catch

Validate before calling

List<Element> matches = input("#email").findAll("tag:label");
if (matches.isEmpty()) {
    System.err.println("no label beside #email — check DOM or wait");
} else {
    Element label = matches.get(0);
}

Try / catch

try {
    Element el = input("#email").find("tag:label");
} catch (DriverException e) {
    if (e.getMessage().startsWith("no element found")) {
        driver.waitFor("#email label"); // then retry
    } else { throw e; }
}

Prevention

Use findAll + empty check when absence is a valid outcome
Wait for dynamically rendered elements first
Double-check positional constraints (rightOf/within) against the DOM
Prefer explicit css/xpath prefixes over bare locators

When it happens

Trigger: Calling finder.find(locator) where the locator matches nothing in the constrained scope — e.g. input('#parent').find('css:label') when no label exists inside the parent, or positional finders like rightOf finding nothing adjacent.

Common situations: DOM structure changed so the target is no longer inside/beside the reference element, waiting is needed before the element renders, mixing up find (throws) vs findAll (returns empty).

Related errors

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/Finder.java:83

     *
     * @param pixels the tolerance in pixels
     * @return a new Finder with the specified tolerance
     */
    public Finder within(double pixels) {
        return new Finder(driver, referenceLocator, position, pixels);
    }

    /**
     * Find the first element matching the locator that satisfies the positional constraint.
     *
     * @param locator the locator for candidate elements
     * @return the first matching element
     * @throws DriverException if no matching element is found
     */
    public Element find(String locator) {
        List<Element> matches = findAll(locator);
        if (matches.isEmpty()) {
            throw new DriverException("no element found " + positionDescription() + " " + referenceLocator + " matching: " + locator);
        }
        return matches.get(0);
    }

    /**
     * Find all elements matching the locator that satisfy the positional constraint.
     *
     * @param locator the locator for candidate elements
     * @return list of matching elements, sorted by distance to reference
     */
    @SuppressWarnings("unchecked")
    public List<Element> findAll(String locator) {
        // Get reference element position
        Map<String, Object> refPos = driver.position(referenceLocator, true);
        double refX = ((Number) refPos.get("x")).doubleValue();
        double refY = ((Number) refPos.get("y")).doubleValue();
        double refWidth = ((Number) refPos.get("width")).doubleValue();
        double refHeight = ((Number) refPos.get("height")).doubleValue();

View on GitHub (pinned to a22eb90246)