{"record":{"id":"d7d1a768b52ffda8","repo":"karatelabs/karate","slug":"timeout-waiting-for-element-locator","errorCode":null,"errorMessage":"timeout waiting for element: ${locator}","messagePattern":"timeout waiting for element: (.+?)","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/driver/cdp/CdpDriver.java","lineNumber":3292,"sourceCode":"    }\n\n    // ========== Wait Methods ==========\n\n    /**\n     * Wait for an element to exist.\n     */\n    public Element waitFor(String locator) {\n        return waitFor(locator, options.getTimeoutDuration());\n    }\n\n    /**\n     * Wait for an element to exist with custom timeout.\n     */\n    public Element waitFor(String locator, Duration timeout) {\n        Element found = pollFor(timeout.toMillis(), options.getRetryInterval(),\n                () -> exists(locator) ? BaseElement.existing(this, locator) : null);\n        if (found == null) {\n            throw new DriverException(\"timeout waiting for element: \" + locator);\n        }\n        return found;\n    }\n\n    /**\n     * Wait for any of the locators to match.\n     */\n    public Element waitForAny(String locator1, String locator2) {\n        return waitForAny(new String[]{locator1, locator2});\n    }\n\n    /**\n     * Wait for any of the locators to match.\n     */\n    public Element waitForAny(String[] locators) {\n        return waitForAny(locators, options.getTimeoutDuration());\n    }\n","sourceCodeStart":3274,"sourceCodeEnd":3310,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/driver/cdp/CdpDriver.java#L3274-L3310","documentation":"driver.waitFor(locator, timeout) polls until exists(locator) is true, using the given timeout and the configured retry interval. If the element never appears within the timeout, Karate throws this DriverException instead of returning an Element.","triggerScenarios":"driver.waitFor(locator, Duration) where the element does not appear within the explicit timeout: wrong selector, element behind an unperformed interaction, element in another frame, or timeout too short for the app's load time.","commonSituations":"Fixed timeout too aggressive on slow CI or cold-started pages; waiting for content that requires login/data setup that did not happen; element appears in a modal that was never opened; selector broken after a UI refactor.","solutions":["Validate the selector against the app state at that point; fix typos/stale ids.","Increase the timeout Duration to cover worst-case load times.","Ensure prerequisite steps (navigation, login, opening the modal) complete before waiting.","Switch to the containing iframe before waiting if the element is inside one; catch DriverException to fail with a custom diagnostic."],"exampleFix":"// before\nElement e = driver.waitFor('#results', Duration.ofSeconds(2)); // too short\n// after\nElement e = driver.waitFor('#results', Duration.ofSeconds(30));","handlingStrategy":"try-catch","validationCode":"// ensure prerequisites are done before waiting\nif (!driver.exists(\"#container\")) throw new IllegalStateException(\"page not ready\");","typeGuard":null,"tryCatchPattern":"try {\n    Element e = driver.waitFor(locator, Duration.ofSeconds(30));\n} catch (Exception e) {\n    if (e.getMessage().startsWith(\"timeout waiting for element\")) {\n        throw new AssertionError(\"element never appeared within timeout: \" + locator, e);\n    } else throw e;\n}","preventionTips":["Budget timeouts for the slowest realistic environment (CI).","Complete all prerequisite navigation/actions before waiting.","Switch to the right frame before waiting for inner elements.","Use stable data-testid style selectors."],"tags":["driver","wait","timeout","element-not-found"],"backgroundTag":"request-timeout","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"}