karatelabs/karate · error · DriverException

frame not found

Error message

frame not found: {locator}

What it means

When switching to a frame by locator, Karate runs an in-page script that matches iframe/frame elements by CSS, XPath, or wildcard and returns frame info (id, name, src). If the script returns null no matching element was found, and Karate throws this DriverException. If it returns an 'error' key instead, the element matched but is not a frame ('locator is not a frame').

Solutions

1. Verify the selector matches an iframe/frame element in DevTools (document.querySelector) and fix the locator
2. Wait for the iframe to exist first (driver.waitFor(locator)) before switchFrame
3. For nested iframes, switch into the parent frame first, then switch again inside it
4. Use the iframe's name/id attribute as a simpler locator if available

Example fix

// before
driver.switchFrame("iframe#pay"); // iframe not yet rendered
// after
driver.waitFor("iframe#pay");
driver.switchFrame("iframe#pay");

Boolean present = (Boolean) driver.script("!!document.querySelector('" + cssLocator + "')");
if (present == null || !present) throw new IllegalStateException("iframe not in DOM yet: " + cssLocator);

try { driver.switchFrame(locator); } catch (DriverException e) { if (e.getMessage().startsWith("frame not found")) { driver.waitFor(locator); driver.switchFrame(locator); } else if (e.getMessage().startsWith("locator is not a frame")) { throw new IllegalArgumentException("selector must match iframe/frame: " + locator); } else throw e; }

When it happens

Trigger: driver.switchFrame(locator) where no <iframe>/<frame> matches the given CSS/XPath/wildcard at evaluation time — wrong selector, frame not yet in DOM, frame nested inside another frame (the script only searches the current frame's document).

Common situations: Typos or wrong casing in CSS selectors; iframes added asynchronously by JS; trying to reach a nested iframe directly from the top frame; shadow-DOM-hosted iframes not reachable by plain CSS/XPath.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• no frame at index: after retries
• locator is not a frame
• {diagnostic: frame switch failed with child-frame url list}
• frame context not received via event, falling back to…
• failed to create isolated world for frame

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/cdp/CdpDriver.java:2321

            currentFrame = null;
        }

        // Wait for frame element to exist (same retry logic as other element operations)
        retryIfNeeded(locator);

        // Find the iframe element and get its frame ID
        String js = Locators.wrapInFunctionInvoke(
                "var e = " + Locators.selector(locator) + ";" +
                        " if (!e) return null;" +
                        " if (e.tagName !== 'IFRAME' && e.tagName !== 'FRAME') return { error: 'not a frame element' };" +
                        " return { " +
                        "   name: e.name || ''," +
                        "   src: e.src || ''" +
                        " }");
        Object result = script(js);

        if (result == null) {
            throw new DriverException("frame not found: " + locator);
        }

        Map<String, Object> frameInfo = (Map<String, Object>) result;
        if (frameInfo.containsKey("error")) {
            throw new DriverException("locator is not a frame: " + locator);
        }

        // Get frame ID from frame tree by matching name or src
        String targetName = (String) frameInfo.get("name");
        String targetSrc = (String) frameInfo.get("src");

        CdpResponse response = cdp.method("Page.getFrameTree").send();
        List<Map<String, Object>> childFrames = response.getResult("frameTree.childFrames");

        // Find matching frame in tree
        String frameId = null;
        String url = null;
        String name = null;

View on GitHub (pinned to a22eb90246)