{"record":{"id":"c682f21d78124a6e","repo":"karatelabs/karate","slug":"no-element-found-positiondescription-referencelocator","errorCode":null,"errorMessage":"no element found {positionDescription} {referenceLocator} matching: {locator}","messagePattern":"no element found (.+?) (.+?) matching: (.+?)","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/driver/Finder.java","lineNumber":83,"sourceCode":"     *\n     * @param pixels the tolerance in pixels\n     * @return a new Finder with the specified tolerance\n     */\n    public Finder within(double pixels) {\n        return new Finder(driver, referenceLocator, position, pixels);\n    }\n\n    /**\n     * Find the first element matching the locator that satisfies the positional constraint.\n     *\n     * @param locator the locator for candidate elements\n     * @return the first matching element\n     * @throws DriverException if no matching element is found\n     */\n    public Element find(String locator) {\n        List<Element> matches = findAll(locator);\n        if (matches.isEmpty()) {\n            throw new DriverException(\"no element found \" + positionDescription() + \" \" + referenceLocator + \" matching: \" + locator);\n        }\n        return matches.get(0);\n    }\n\n    /**\n     * Find all elements matching the locator that satisfy the positional constraint.\n     *\n     * @param locator the locator for candidate elements\n     * @return list of matching elements, sorted by distance to reference\n     */\n    @SuppressWarnings(\"unchecked\")\n    public List<Element> findAll(String locator) {\n        // Get reference element position\n        Map<String, Object> refPos = driver.position(referenceLocator, true);\n        double refX = ((Number) refPos.get(\"x\")).doubleValue();\n        double refY = ((Number) refPos.get(\"y\")).doubleValue();\n        double refWidth = ((Number) refPos.get(\"width\")).doubleValue();\n        double refHeight = ((Number) refPos.get(\"height\")).doubleValue();","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/driver/Finder.java#L65-L101","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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"],"exampleFix":"// before\nElement label = input(\"#email\").find(\"tag:label\");\n// after\nList<Element> labels = input(\"#email\").findAll(\"tag:label\");\nif (!labels.isEmpty()) { Element label = labels.get(0); ... }","handlingStrategy":"try-catch","validationCode":"List<Element> matches = input(\"#email\").findAll(\"tag:label\");\nif (matches.isEmpty()) {\n    System.err.println(\"no label beside #email — check DOM or wait\");\n} else {\n    Element label = matches.get(0);\n}","typeGuard":null,"tryCatchPattern":"try {\n    Element el = input(\"#email\").find(\"tag:label\");\n} catch (DriverException e) {\n    if (e.getMessage().startsWith(\"no element found\")) {\n        driver.waitFor(\"#email label\"); // then retry\n    } else { throw e; }\n}","preventionTips":["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"],"tags":["driver","ui","selector"],"backgroundTag":"element-not-found","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}