{"record":{"id":"49bd183ee27595bf","repo":"stablyai/orca","slug":"browser-ref-not-found","errorCode":"browser_ref_not_found","errorMessage":"Element ref ${ref} was not found. Run 'orca snapshot' to see available refs.","messagePattern":"Element ref (.+?) was not found\\. Run 'orca snapshot' to see available refs\\.","errorType":"exception","errorClass":"BrowserError","httpStatus":null,"severity":"warning","filePath":"src/main/browser/cdp-bridge.ts","lineNumber":1360,"sourceCode":"\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\n        state.navigationId = null\n        throw new BrowserError(\n          'browser_stale_ref',\n          \"The page has navigated since the last snapshot. Run 'orca snapshot' to get fresh refs.\"\n        )\n      }\n    }\n","sourceCodeStart":1342,"sourceCodeEnd":1378,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/browser/cdp-bridge.ts#L1342-L1378","documentation":"The ref string provided to resolveRef() is not a key in the current snapshot's refMap. The element either wasn't captured in the snapshot (e.g., it was in a collapsed subtree or aria-hidden region excluded from the AX tree), or the ref value originates from a different/older snapshot whose refs no longer apply. This is distinct from browser_stale_ref (812) which means no snapshot exists at all.","triggerScenarios":"Using a ref from a previous snapshot after a new snapshot was taken; referencing an element that was hidden/collapsed and excluded from the AX snapshot; typo or truncation in the ref string.","commonSituations":"Agent caches refs across snapshots; element is in a shadow DOM or aria-hidden region the AX tree omits; ref string was copy-pasted incorrectly.","solutions":["Run 'orca snapshot' and use only refs from the latest snapshot result.","Do not cache or hardcode refs across navigations or snapshots.","Verify the target element is visible and present in the AX tree before referencing it."],"exampleFix":"// before\nawait bridge.click('old-ref-from-previous-snapshot')\n\n// after\nconst snap = await bridge.snapshot()\nconst ref = snap.refs.find(r => r.role === 'button' && r.name === 'Submit')?.ref\nif (!ref) throw new Error('Submit button not found in snapshot')\nawait bridge.click(ref)","handlingStrategy":"validation","validationCode":"const snap = await bridge.snapshot()\nconst refEntry = snap.refs.find(r => r.ref === ref)\nif (!refEntry) {\n  throw new Error(`Ref ${ref} not in current snapshot. Available: ${snap.refs.map(r => r.ref).join(', ')}`)\n}\nawait bridge.click(ref)","typeGuard":null,"tryCatchPattern":"try {\n  await bridge.click(ref)\n} catch (e) {\n  if (e instanceof BrowserError && e.code === 'browser_ref_not_found') {\n    const snap = await bridge.snapshot()\n    const fresh = snap.refs.find(r => r.role === desiredRole && r.name === desiredName)\n    if (fresh) await bridge.click(fresh.ref)\n    else throw e\n  }\n  throw e\n}","preventionTips":["Use only refs from the most recent snapshot() result — never cache or hardcode refs.","Verify the target element is present and visible in the AX tree before referencing it.","After navigation or re-render, re-snapshot and re-resolve refs by role+name."],"tags":["snapshot","refs","stale","not-found"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}