{"record":{"id":"91055e49d5de9612","repo":"stablyai/orca","slug":"element-not-found","errorCode":"element_not_found","errorMessage":"element ${index} is not in the current cached snapshot; run get-app-state again and use a fresh element index","messagePattern":"element (.+?) is not in the current cached snapshot; run get-app-state again and use a fresh element index","errorType":"error_code","errorClass":"RuntimeClientError","httpStatus":null,"severity":"warning","filePath":"src/main/computer/desktop-script-action.ts","lineNumber":224,"sourceCode":"  return withoutStaleWindowTarget\n}\n\nexport function isWindowChangedAction(action: ComputerActionMetadata): boolean {\n  return (\n    action.verification?.state === 'unverified' && action.verification.reason === 'window_changed'\n  )\n}\n\nexport function elementParam(\n  snapshot: BridgeSnapshot | null,\n  index: number | undefined\n): BridgeElement | undefined {\n  if (index === undefined) {\n    return undefined\n  }\n  const element = snapshot?.elements?.find((candidate) => candidate.index === index)\n  if (!element) {\n    throw new RuntimeClientError(\n      'element_not_found',\n      `element ${index} is not in the current cached snapshot; run get-app-state again and use a fresh element index`\n    )\n  }\n  return element\n}\n","sourceCodeStart":206,"sourceCodeEnd":231,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/computer/desktop-script-action.ts#L206-L231","documentation":"elementParam looks up an element by `index` inside the cached snapshot's `elements` array. If no element matches, it throws element_not_found. Element indexes are valid only against the most recent get-app-state snapshot; any UI change invalidates them. This is the most common recoverable computer-use error.","triggerScenarios":"Calling click, scroll, drag, setValue, or performSecondaryAction with an elementIndex from a stale snapshot; after the app re-rendered; after a window change; an index that never existed.","commonSituations":"Reusing element indexes across multiple actions without refreshing; the app window changed between snapshot and action; concurrent actions invalidated the cache.","solutions":["Call get-app-state (snapshot) again to refresh element indexes.","Use the elementIndex from the immediately preceding snapshot.","After any window-changing action, re-snapshot before targeting elements again."],"exampleFix":"// before\nconst snap1 = await client.snapshot({ app: 'Safari' })\n// ... app changes ... \nawait client.action('click', { app: 'Safari', elementIndex: snap1.elements[0].index })\n// after\nconst fresh = await client.snapshot({ app: 'Safari' })\nawait client.action('click', { app: 'Safari', elementIndex: fresh.elements[0].index })","handlingStrategy":"retry","validationCode":"function elementExists(snapshot, index) {\n  return snapshot?.elements?.some((e) => e.index === index) ?? false\n}\nif (!elementExists(currentSnapshot, params.elementIndex)) {\n  currentSnapshot = await client.snapshot({ app: params.app })\n}","typeGuard":null,"tryCatchPattern":"try {\n  return await client.action('click', params)\n} catch (err) {\n  if (err instanceof RuntimeClientError && err.code === 'element_not_found') {\n    await client.snapshot({ app: params.app })\n    return client.action('click', params) // retry once with a fresh snapshot\n  }\n  throw err\n}","preventionTips":["Always snapshot immediately before element-based actions.","Re-snapshot after any window change.","Treat element indexes as single-use."],"tags":["element-not-found","stale-snapshot","accessibility"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}