{"record":{"id":"d0c9dde322c6b8ae","repo":"microsoft/playwright","slug":"invalid-frame-in-aria-ref-selector-selector","errorCode":null,"errorMessage":"Invalid frame in aria-ref selector \"${selector}\"","messagePattern":"Invalid frame in aria-ref selector \"(.+?)\"","errorType":"exception","errorClass":"InvalidSelectorError","httpStatus":null,"severity":"error","filePath":"packages/playwright-core/src/server/frameSelectors.ts","lineNumber":119,"sourceCode":"      return [];\n\n    // Note: adopting elements one by one may be slow. If we encounter the issue here,\n    // we might introduce 'useMainContext' option or similar to speed things up.\n    const targetContext = await elementHandles[0]._frame.mainContext();\n    return Promise.all(elementHandles.map(handle => adoptIfNeeded(handle, targetContext)));\n  }\n\n  private _jumpToAriaRefFrameIfNeeded(selector: string, info: SelectorInfo, frame: Frame): Frame {\n    if (info.parsed.parts[0].name !== 'aria-ref')\n      return frame;\n    const body = info.parsed.parts[0].body as string;\n    const match = body.match(/^f(\\d+)e\\d+$/);\n    if (!match)\n      return frame;\n    const frameSeq = +match[1];\n    const jumptToFrame = this.frame._page.frameManager.frames().find(frame => frame.seq === frameSeq);\n    if (!jumptToFrame)\n      throw new InvalidSelectorError(`Invalid frame in aria-ref selector \"${selector}\"`);\n    return jumptToFrame;\n  }\n\n  private async _resolveFramesForSelector(selector: string, options: types.StrictOptions & { noDefaultPierce?: boolean } = {}, scope?: ElementHandle): Promise<SelectorInFrame[]> {\n    const pierceByDefault = !!this.frame._page.browserContext._options.pierceFrames && !options.noDefaultPierce;\n    const { pierce, chunks } = splitSelectorByFrame(selector, pierceByDefault);\n    for (const chunk of chunks) {\n      visitAllSelectorParts(chunk, (part, nested) => {\n        if (nested && part.name === 'internal:control' && part.body === 'enter-frame') {\n          const locator = asLocator(this.frame._page.browserContext._browser.sdkLanguage(), selector);\n          throw new InvalidSelectorError(`Frame locators are not allowed inside composite locators, while querying \"${locator}\"`);\n        }\n        if (nested && pierce) {\n          const locator = asLocator(this.frame._page.browserContext._browser.sdkLanguage(), selector);\n          throw new InvalidSelectorError(`Composite locators are not supported with piercing frames, while querying \"${locator}\"`);\n        }\n      });\n    }","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/microsoft/playwright/blob/c8fc3bf8d31542d59b4d4d9eaab1df93ff541dc6/packages/playwright-core/src/server/frameSelectors.ts#L101-L137","documentation":"During internal aria-ref resolution (used by recorder/locator snapshots), Playwright extracts a frame sequence id from an aria-ref like 'f<seq>e<n>'. If no live frame in the page matches that sequence id, it throws InvalidSelectorError indicating the ref points at a frame that no longer exists.","triggerScenarios":"Replaying a captured aria-ref/locator snapshot against a page where the referenced iframe has been removed, navigated, or not yet attached. Typically produced by recorder/replay or by reusing a stale ref captured in a previous session.","commonSituations":"Locator recorded against one page state and replayed after the DOM/iframes changed; iframes added dynamically and not yet present; cross-frame recording in flaky tests; recorder artifacts from older builds.","solutions":["Re-capture the selector/locator against the current page state.","Wait for the target iframe to attach (frameLocator + waitFor) before resolving.","Prefer stable, semantic locators (getByRole) over recorded refs when possible.","Avoid reusing aria-refs across page navigations or sessions."],"exampleFix":"null","handlingStrategy":"validation","validationCode":"// Ensure the frame exists before using a recorded locator\nconst frames = page.frames();\nif (!frames.some(f => f.url().includes(expectedHost))) await page.waitForURL(expectedHost);","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Treat aria-refs as ephemeral; do not hardcode them.","Re-record after intentional DOM/iframe restructuring."],"tags":["selector","aria-ref","frames"],"backgroundTag":null,"analyzedSha":"c8fc3bf8d31542d59b4d4d9eaab1df93ff541dc6","analyzedAt":"2026-08-12T07:26:36.950Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}