Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
export type ComputerUseErrorRecoveryData = {
nextSteps: string[]
}
export function computerUseErrorRecoveryData(
code: string,
message?: string
): ComputerUseErrorRecoveryData | undefined {
switch (code) {
case 'app_not_found':
return recoverWith(
'Run `orca computer list-apps --json` and retry with the exact app name or bundle ID.',
'If the target is a website or web app such as Gmail, choose the desktop browser app/window that contains it; `orca computer` app selectors refer to desktop apps, not website names.',
'Do not retry the same `orca computer ... --app <web app>` command unchanged.',
'If the desired browser is not listed, open or focus that browser first, then retry `orca computer list-apps --json` and `orca computer list-windows --app <browser> --json`.'
)
case 'app_blocked':
return recoverWith(
'Do not continue with this app through computer-use; choose a non-sensitive target or ask the user to handle it manually.'
)
case 'window_not_found':
return recoverWith(
'Run `orca computer list-windows --app <app> --json` and target one of the listed windows.',
'If the app is listed but no usable window is visible, retry observation once with `--restore-window`.',
'If no window is listed, open or focus the app first; `orca computer` does not launch closed desktop apps.'
)
case 'window_not_focused':
if (message?.includes('may already have been delivered')) {
return recoverWith(
'Run `orca computer get-app-state --app <app> --json` and verify whether the intended action already occurred before retrying.',
'Do not retry the click if it already took effect; otherwise bring the target window forward and use fresh state before trying again.'
)
}
return recoverWith(
'Retry once with `--restore-window`.',
'If `--restore-window` was already used, stop retrying restore; bring the app forward manually, check permissions, or prefer `set-value` for editable fields.'
)
case 'background_unavailable':
return recoverWith(
'If the message names a popup menu or `<select>`, set its option with `orca computer set-value` on that element instead of clicking.',
'Otherwise retry once with `--restore-window`; that brings the app forward and uses foreground input, so tell the user it will take over their screen.'
)
case 'window_stale':
return recoverWith(
'Run `orca computer list-windows --app <app> --json` and choose a current window selector.',
'Then rerun `orca computer get-app-state --app <app> --json` before acting.'
)
case 'provider_incompatible':
return recoverWith(
'Run `orca computer capabilities --json` and verify the local provider supports the requested operation.',
'Update Orca or use a supported platform/provider path before retrying.'
)
case 'unsupported_capability':
return recoverWith(
'Run `orca computer capabilities --json` and choose a supported action.',
'Use a semantic alternative such as `set-value` or `click`, or install the missing desktop dependency if the error names one.'
)
case 'permission_denied':
return recoverWith(
'Run `orca computer permissions --json`, or `orca computer permissions --id accessibility --json` / `--id screenshots --json` when the message names one missing permission.',
'For remote or SSH targets, verify the command is running inside an active graphical desktop session.'
)
case 'element_not_found':
return recoverWith(
'Run `orca computer get-app-state --app <app> --json` again and use an element index from the fresh tree.',
'Do not infer valid indexes from `elementCount` or reuse indexes after navigation, scrolling, focus changes, or delays.'
)
case 'element_not_clickable':
return recoverWith(
'Choose a nearby parent or child element that has an actionable frame.',
'If using coordinates, derive window-local coordinates from the latest screenshot/state for the same target window.'
)
case 'action_not_supported':
return recoverWith(
'Inspect the element in a fresh `get-app-state` result and use one of its advertised secondary actions.',
'If no suitable action is listed, use `click`, `set-value`, or another semantic action instead.'
)
case 'value_not_settable':
return recoverWith(
'Choose a settable text element from a fresh `get-app-state` result.',
'If the target cannot accept direct value writes, focus it and use keyboard input only after inspecting the returned state.'
)
case 'invalid_argument':
return recoverWith(
'Fix the command flags or RPC params exactly as described by the error message.',
'Do not retry the same command unchanged.'
)
case 'action_timeout':
return recoverWith(
'Run `orca computer get-app-state --app <app> --json` before retrying so you know whether the UI changed.',
'Retry with a simpler semantic action or `--no-screenshot` if observation is slow; do not repeat the same timed-out action blindly.'
)
case 'verification_failed':
return recoverWith(
'Run `orca computer get-app-state --app <app> --json` and check which field holds the value; another field may have changed instead.',
'Do not retry the same `set-value` unchanged. For editable text, click the field and confirm focus, select all (`cmd+a` on macOS, `ctrl+a` on Windows/Linux), then use `type-text` and inspect the resulting value.'
)
case 'screenshot_failed':
return recoverWith(
'If the accessibility tree is sufficient, rerun the command with `--no-screenshot` instead of retrying the same screenshot capture.',
'If the message mentions Screen Recording or screenshots permission, run `orca computer permissions --id screenshots --json` and grant access before retrying.',
'If the message mentions the payload cap, target a smaller/current window or use `--no-screenshot`.'
)
case 'accessibility_error':
// Why: an Orca server installed before it bundled computer use reports only this exit (#31777).
if (message?.startsWith('computer sidecar exited with code')) {
return recoverWith(
'If this targets an Orca server (`orca serve`, SSH or WSL), its install may not include computer use: update or reprovision the server, then retry.',
'Run `orca computer capabilities --json` to confirm the provider is available before retrying.'
)
}
return recoverWith(
'Run `orca computer capabilities --json` to confirm the provider is available before retrying.',
'If the message mentions permissions, run `orca computer permissions --id accessibility --json` and grant access.',
'Do not loop on the same action if provider availability or permissions remain unchanged.'
)
default:
return undefined
}
}
function recoverWith(...nextSteps: string[]): ComputerUseErrorRecoveryData {
return { nextSteps }
}