{"record":{"id":"73e11b8cbafdfb5f","repo":"garrytan/gstack","slug":"frame-not-found-target","errorCode":null,"errorMessage":"Frame not found: ${target}","messagePattern":"Frame not found: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"browse/src/meta-commands.ts","lineNumber":1029,"sourceCode":"      const page = bm.getPage();\n      let frame: Frame | null = null;\n\n      if (target === '--name') {\n        if (!args[1]) throw new Error('Usage: frame --name <name>');\n        frame = page.frame({ name: args[1] });\n      } else if (target === '--url') {\n        if (!args[1]) throw new Error('Usage: frame --url <pattern>');\n        frame = page.frame({ url: new RegExp(escapeRegExp(args[1])) });\n      } else {\n        // CSS selector or @ref for the iframe element\n        const resolved = await bm.resolveRef(target);\n        const locator = 'locator' in resolved ? resolved.locator : page.locator(resolved.selector);\n        const elementHandle = await locator.elementHandle({ timeout: 5000 });\n        frame = await elementHandle?.contentFrame() ?? null;\n        await elementHandle?.dispose();\n      }\n\n      if (!frame) throw new Error(`Frame not found: ${target}`);\n      bm.setFrame(frame);\n      bm.clearRefs();\n      return `Switched to frame: ${frame.url()}`;\n    }\n\n    // ─── UX Audit ─────────────────────────────────────\n    case 'ux-audit': {\n      const page = bm.getPage();\n\n      // Extract page structure for UX behavioral analysis\n      // Agent interprets the data and applies Krug's 6 usability tests\n      // Uses textContent (not innerText) to avoid layout computation on large DOMs\n      const data = await page.evaluate(() => {\n        const HEADING_CAP = 50;\n        const INTERACTIVE_CAP = 200;\n        const TEXT_BLOCK_CAP = 50;\n\n        // Site ID: logo or brand element","sourceCodeStart":1011,"sourceCodeEnd":1047,"githubUrl":"https://github.com/garrytan/gstack/blob/94993f74012782fd94416dd44b8314f6363a13a4/browse/src/meta-commands.ts#L1011-L1047","documentation":"After resolving the target via `--name`, `--url`, or an element selector/ref, the command checks whether a `Frame` was found (line 1029). If Playwright returned null — no frame matched the name/URL, or the resolved element had no content frame — the command throws, echoing the target. The command then sets the frame and clears refs only on success.","triggerScenarios":"`browse frame --name nope`, `browse frame --url 'does-not-exist\\.com'`, or `browse frame @e5` where `@e5` is not an `<iframe>`/has no content frame.","commonSituations":"iframes loading asynchronously (frame not yet present), wrong name/URL pattern, element ref pointing to a non-iframe, cross-origin frames Playwright cannot enumerate, or a frame that has navigated away.","solutions":["Verify the iframe exists with a `snapshot`/`text` first; wait for it if it loads lazily.","Check the frame name/URL against the page's actual frames (e.g. via `cdp` or DOM inspection).","Ensure the element ref points to an `<iframe>` element, not a wrapper `<div>`.","For dynamic frames, retry after the iframe's network request settles."],"exampleFix":"// before\nbrowse frame @e5  // @e5 is a div, not an iframe\n// after\nbrowse frame iframe.widget","handlingStrategy":"try-catch","validationCode":"// Best-effort: confirm the iframe exists before switching.\nconst frames = bm.getPage().frames();\nconst matches = frames.filter(f => /* name/url/selector logic */);\nif (matches.length === 0) throw new Error('No matching frame; page may still be loading');","typeGuard":null,"tryCatchPattern":"try { await browse.frame(target); }\ncatch (err) {\n  if (/Frame not found/.test(err.message)) {\n    await bm.getPage().waitForLoadState('networkidle', { timeout: 3000 }).catch(() => {});\n    return browse.frame(target); // single retry after settle\n  }\n  throw err;\n}","preventionTips":["Wait for the iframe element to attach before calling `frame`.","Prefer `--name`/`--url` for stable identification over element refs that can shift.","Confirm the target element is actually an `<iframe>` before resolving by ref."],"tags":["frame","not-found","playwright"],"backgroundTag":null,"analyzedSha":"94993f74012782fd94416dd44b8314f6363a13a4","analyzedAt":"2026-08-12T04:06:23.140Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}