{"record":{"id":"c0ba11b4f68c17c8","repo":"stablyai/orca","slug":"browser-stale-ref","errorCode":"browser_stale_ref","errorMessage":"No snapshot exists for this tab. Run 'orca snapshot' first.","messagePattern":"No snapshot exists for this tab\\. Run 'orca snapshot' first\\.","errorType":"exception","errorClass":"BrowserError","httpStatus":null,"severity":"warning","filePath":"src/main/browser/cdp-bridge.ts","lineNumber":1352,"sourceCode":"        })\n      ])\n    }\n  }\n\n  private senderForRef(guest: Electron.WebContents, ref: RefEntry): CdpCommandSender {\n    return ref.sessionId ? this.makeCdpSender(guest, ref.sessionId) : this.makeCdpSender(guest)\n  }\n\n  private async resolveRef(\n    guest: Electron.WebContents,\n    sender: CdpCommandSender,\n    ref: string\n  ): Promise<RefEntry> {\n    const tabId = this.resolveTabId(guest.id)\n    const state = this.getOrCreateTabState(tabId)\n\n    if (!state.snapshotResult) {\n      throw new BrowserError(\n        'browser_stale_ref',\n        \"No snapshot exists for this tab. Run 'orca snapshot' first.\"\n      )\n    }\n\n    const entry = state.snapshotResult.refMap.get(ref)\n    if (!entry) {\n      throw new BrowserError(\n        'browser_ref_not_found',\n        `Element ref ${ref} was not found. Run 'orca snapshot' to see available refs.`\n      )\n    }\n\n    // Why: iframe refs use a child session with independent nav history, so a parent-navId check would falsely reject them.\n    if (!entry.sessionId) {\n      const currentNavId = await this.getNavigationId(sender)\n      if (state.navigationId && currentNavId !== state.navigationId) {\n        state.snapshotResult = null","sourceCodeStart":1334,"sourceCodeEnd":1370,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/browser/cdp-bridge.ts#L1334-L1370","documentation":"Element-ref commands (click, fill, hover, scroll, etc.) call resolveRef() which requires a prior accessibility snapshot to map element refs to CDP backendNodeIds. If state.snapshotResult is null, no snapshot has been taken for this tab, or a previous snapshot was invalidated (by navigation, debugger detach, or a stale-ref clear). Without a refMap, the command cannot resolve which DOM node to act on. The message tells the user to run 'orca snapshot' first.","triggerScenarios":"Calling click(ref) or fill(ref, value) before calling snapshot(); after a navigation that cleared the snapshot; after a debugger detach that nulled snapshotResult.","commonSituations":"Agent skips the snapshot step; snapshot was cleared by Page.frameNavigated and the agent retries a ref-based action without re-snapshotting; fresh tab with no snapshot yet.","solutions":["Call snapshot() (or 'orca snapshot') before any ref-based command.","Re-snapshot after any navigation (goto, link-click navigation, redirect).","Re-snapshot after recovering from a browser_debugger_detached error."],"exampleFix":"// before\nawait bridge.click('btn-submit')\n\n// after\nawait bridge.snapshot()\nawait bridge.click('btn-submit')","handlingStrategy":"validation","validationCode":"// CdpBridge doesn't expose snapshotResult publicly; callers should track snapshot state\nlet hasSnapshot = false\nawait bridge.snapshot()\nhasSnapshot = true\n// before any ref-based command:\nif (!hasSnapshot) { await bridge.snapshot() }\nawait bridge.click(ref)","typeGuard":null,"tryCatchPattern":"try {\n  await bridge.click(ref)\n} catch (e) {\n  if (e instanceof BrowserError && e.code === 'browser_stale_ref' && /No snapshot/.test(e.message)) {\n    await bridge.snapshot()\n    await bridge.click(ref)\n  }\n  throw e\n}","preventionTips":["Always call snapshot() before any ref-based command (click, fill, hover, scroll).","Re-snapshot after navigation, debugger detach, or any error that may have cleared the snapshot.","In agent loops, snapshot once per page state and invalidate on navigation."],"tags":["snapshot","refs","precondition","accessibility"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}