{"record":{"id":"ddb74fbb24c5654c","repo":"karatelabs/karate","slug":"diagnostic-frame-switch-failed-with-child-frame-url-list","errorCode":null,"errorMessage":"{diagnostic: frame switch failed with child-frame url list}","messagePattern":"\\{diagnostic: frame switch failed with child-frame url list\\}","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/driver/cdp/CdpDriver.java","lineNumber":2464,"sourceCode":"            name = matched[2];\n        }\n\n        if (frameId == null) {\n            cdp.setSessionId(pageSessionId);\n            StringBuilder diag = new StringBuilder(\"could not find frame for locator: \").append(locator);\n            diag.append(\" (targetName='\").append(targetName).append(\"', targetSrc='\").append(targetSrc).append(\"'\");\n            if (!oopifTargets.isEmpty()) {\n                diag.append(\", knownOopifs=[\");\n                boolean first = true;\n                for (Map<String, Object> info : oopifTargets.values()) {\n                    if (!first) diag.append(\", \");\n                    diag.append(info.get(\"url\"));\n                    first = false;\n                }\n                diag.append(\"]\");\n            }\n            diag.append(\")\");\n            throw new DriverException(diag.toString());\n        }\n\n        currentFrame = new Frame(frameId, url, name);\n        logger.debug(\"switched to frame by locator {}: {}\", locator, currentFrame);\n\n        // Ensure we have execution context for this frame\n        ensureFrameContext(frameId);\n    }\n\n    /**\n     * Get the current frame, or null if in main frame.\n     *\n     * @return the current frame info, or null\n     */\n    public Map<String, Object> getCurrentFrame() {\n        if (currentFrame == null) {\n            return null;\n        }","sourceCodeStart":2446,"sourceCodeEnd":2482,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/driver/cdp/CdpDriver.java#L2446-L2482","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Wait for the frame to load before switching, e.g. driver.waitFor('iframe...') or retry the switch with retry until.","Read the child-frame url list in the message and correct the locator to match an actual frame name or src.","Switch by frame index or by exact src attribute as seen in the diagnostic.","Check that the frame is not lazily created/destroyed by app code; add an explicit wait for the app state that creates it."],"exampleFix":"// before\ndriver.switchFrame('checkout');\n// after\ndriver.waitFor('iframe#checkout-frame');\ndriver.switchFrame('iframe#checkout-frame');","handlingStrategy":"retry","validationCode":"// wait until the child frame is present before switching\nretryUntil(() -> driver.script(\"return window.frames.length > 0\", null, Boolean.class));","typeGuard":null,"tryCatchPattern":"try {\n    driver.switchFrame(locator);\n} catch (Exception e) {\n    if (e.getMessage().contains(\"frame switch failed\")) {\n        sleep(500);\n        driver.switchFrame(locator); // one retry after frame loads\n    } else throw e;\n}","preventionTips":["Wait for iframe load events before switching frames.","Cross-check frame name/src against the diagnostic url list in the message.","Prefer switching by index when names are dynamic.","Re-enter the frame after each top-level navigation."],"tags":["driver","iframe","frame-switch","cdp","diagnostics"],"backgroundTag":"resource-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"}