stablyai/orca · warning · RuntimeClientError

element_not_found

element_not_found

Error message

element ${index} is not in the current cached snapshot; run get-app-state again and use a fresh element index

What it means

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.

Source

Thrown at src/main/computer/desktop-script-action.ts:224

  return withoutStaleWindowTarget
}

export function isWindowChangedAction(action: ComputerActionMetadata): boolean {
  return (
    action.verification?.state === 'unverified' && action.verification.reason === 'window_changed'
  )
}

export function elementParam(
  snapshot: BridgeSnapshot | null,
  index: number | undefined
): BridgeElement | undefined {
  if (index === undefined) {
    return undefined
  }
  const element = snapshot?.elements?.find((candidate) => candidate.index === index)
  if (!element) {
    throw new RuntimeClientError(
      'element_not_found',
      `element ${index} is not in the current cached snapshot; run get-app-state again and use a fresh element index`
    )
  }
  return element
}

View on GitHub (pinned to 1136503c6a)

Solutions

1. Call get-app-state (snapshot) again to refresh element indexes.
2. Use the elementIndex from the immediately preceding snapshot.
3. After any window-changing action, re-snapshot before targeting elements again.

Example fix

// before
const snap1 = await client.snapshot({ app: 'Safari' })
// ... app changes ... 
await client.action('click', { app: 'Safari', elementIndex: snap1.elements[0].index })
// after
const fresh = await client.snapshot({ app: 'Safari' })
await client.action('click', { app: 'Safari', elementIndex: fresh.elements[0].index })

function elementExists(snapshot, index) {
  return snapshot?.elements?.some((e) => e.index === index) ?? false
}
if (!elementExists(currentSnapshot, params.elementIndex)) {
  currentSnapshot = await client.snapshot({ app: params.app })
}

try {
  return await client.action('click', params)
} catch (err) {
  if (err instanceof RuntimeClientError && err.code === 'element_not_found') {
    await client.snapshot({ app: params.app })
    return client.action('click', params) // retry once with a fresh snapshot
  }
  throw err
}

When it happens

Trigger: 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.

Common situations: Reusing element indexes across multiple actions without refreshing; the app window changed between snapshot and action; concurrent actions invalidated the cache.

Related errors

• {action} is not a valid secondary action
• element value is not settable
• browser_stale_ref
• accessibility_error
• accessibility_error

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/91055e49d5de9612. Report an issue: GitHub.