\n * Action JS must fail loudly on a null resolve. The two alternatives are both worse:\n * a silent no-op strands the caller with a downstream symptom far from the cause (an\n * empty field, an unfired event), and an unguarded deref reports a cryptic\n * \"Cannot read properties of null\" against generated source with no locator in it.\n *
\n *\n * {@link #SCROLL_JS_FUNCTION} deliberately keeps its no-op-on-missing contract\n * instead — scrolling something absent is harmless, and that behavior is pinned by\n * a test. Read actions ({@link #textJs}, {@link #valueJs}, …) likewise stay\n * null-tolerant and return null.\n *
\n */\n private static String notFoundGuard(String var, String locator) {\n return \" if (!\" + var + \") throw new Error(\\\"\" + ELEMENT_NOT_FOUND + \": \" + escapeForJs(locator) + \"\\\");\";\n }\n\n /**\n * Generate JS to get element position.\n */\n public static String getPositionJs(String locator) {\n String js = \"var e = \" + selector(locator) + \";\" +\n notFoundGuard(\"e\", locator) +\n \" var r = e.getBoundingClientRect();\" +\n \" var dx = window.scrollX; var dy = window.scrollY;\" +\n \" return { x: r.x + dx, y: r.y + dy, width: r.width, height: r.height }\";\n return wrapInFunctionInvoke(js);\n }\n\n /**\n * Generate JS to focus an element with cursor at end.\n */\n public static String focusJs(String locator) {","sourceCodeStart":422,"sourceCodeEnd":458,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/driver/Locators.java#L422-L458","documentation":"notFoundGuard injects a JS guard into generated locator expressions that throws an in-page Error with code KARATE_ELEMENT_NOT_FOUND when the target element is missing. It is applied to write/interaction actions where acting on a missing element is not harmless (unlike scroll or read actions, which stay null-tolerant).","triggerScenarios":"Calling an action API (click/input/clear etc. via js-built locators) whose element does not exist in the DOM at call time; the locator resolves to null inside the browser so the injected guard throws.","commonSituations":"Not waiting for SPA content to render, wrong locator after a UI redesign, element present only conditionally (popup shown on some flows), typos in css/xpath.","solutions":["Add a waitFor for the element before performing the action","Verify the locator against the rendered DOM (log document queries)","Retry with retry/retryUntil until the element appears","Use null-tolerant reads or check existence first if the element is optional"],"exampleFix":"// before\ndriver.click(\"#submit\"); // may throw KARATE_ELEMENT_NOT_FOUND\n// after\ndriver.waitFor(\"#submit\");\ndriver.click(\"#submit\");","handlingStrategy":"try-catch","validationCode":"Object exists = driver.script(\"!!document.querySelector('\" + cssEscaped + \"')\");\nif (!Boolean.TRUE.equals(exists)) {\n driver.waitFor(\"#submit\");\n}","typeGuard":null,"tryCatchPattern":"try {\n driver.click(\"#submit\");\n} catch (RuntimeException e) {\n if (e.getMessage().contains(\"KARATE_ELEMENT_NOT_FOUND\")) {\n driver.waitFor(\"#submit\");\n driver.click(\"#submit\");\n } else { throw e; }\n}","preventionTips":["waitFor before every write action on dynamic content","Re-verify locators after UI redesigns","Check conditional elements exist before interacting (popups, banners)","Remember scroll/read actions are null-tolerant but write actions are not"],"tags":["driver","ui","element-not-found"],"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"}