karatelabs/karate · error · DriverException

{diagnostic: frame switch failed with child-frame url list}

Error message

{diagnostic: frame switch failed with child-frame url list}

What it means

This diagnostic error is thrown when a frame switch by locator fails: Karate could not match the requested locator to any child frame and builds a diagnostic message listing the child-frame URLs it saw, then throws a DriverException.

Solutions

1. Wait for the frame to load before switching, e.g. driver.waitFor('iframe...') or retry the switch with retry until.
2. Read the child-frame url list in the message and correct the locator to match an actual frame name or src.
3. Switch by frame index or by exact src attribute as seen in the diagnostic.
4. Check that the frame is not lazily created/destroyed by app code; add an explicit wait for the app state that creates it.

Example fix

// before
driver.switchFrame('checkout');
// after
driver.waitFor('iframe#checkout-frame');
driver.switchFrame('iframe#checkout-frame');

// wait until the child frame is present before switching
retryUntil(() -> driver.script("return window.frames.length > 0", null, Boolean.class));

try {
    driver.switchFrame(locator);
} catch (Exception e) {
    if (e.getMessage().contains("frame switch failed")) {
        sleep(500);
        driver.switchFrame(locator); // one retry after frame loads
    } else throw e;
}

When it happens

Trigger: driver.switchFrame(locator) where the locator's name/src does not match any child frame currently attached to the page; the diagnostic suffix includes the child-frame url list captured at failure time.

Common situations: Frame not yet loaded when the switch is attempted (no wait before switch); frame was removed/reloaded so name/src changed; cross-origin frame whose url differs from expectations; locator references a top-level document instead of a child frame.

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
• frame not found
• locator is not a frame
• inputFile: element did not resolve to a DOM node
• inputFile failed: | locator: | files

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

Appendix: source

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

            name = matched[2];
        }

        if (frameId == null) {
            cdp.setSessionId(pageSessionId);
            StringBuilder diag = new StringBuilder("could not find frame for locator: ").append(locator);
            diag.append(" (targetName='").append(targetName).append("', targetSrc='").append(targetSrc).append("'");
            if (!oopifTargets.isEmpty()) {
                diag.append(", knownOopifs=[");
                boolean first = true;
                for (Map<String, Object> info : oopifTargets.values()) {
                    if (!first) diag.append(", ");
                    diag.append(info.get("url"));
                    first = false;
                }
                diag.append("]");
            }
            diag.append(")");
            throw new DriverException(diag.toString());
        }

        currentFrame = new Frame(frameId, url, name);
        logger.debug("switched to frame by locator {}: {}", locator, currentFrame);

        // Ensure we have execution context for this frame
        ensureFrameContext(frameId);
    }

    /**
     * Get the current frame, or null if in main frame.
     *
     * @return the current frame info, or null
     */
    public Map<String, Object> getCurrentFrame() {
        if (currentFrame == null) {
            return null;
        }

View on GitHub (pinned to a22eb90246)