stablyai/orca · error · RuntimeClientError

incompatible_runtime

incompatible_runtime

Error message

The running Orca runtime is too old to add accounts from the CLI. Update or restart Orca and try again.

What it means

Thrown by assertAccountImportSupported (code 'incompatible_runtime') when the running Orca runtime's status.get response does not advertise the ACCOUNT_IMPORT_RUNTIME_CAPABILITY. The CLI can add accounts only if the runtime it talks to supports account import; an older/older-running runtime lacks the RPC handler and would otherwise fail opaquely deep in the OAuth flow. This check fails fast before the expensive login round trip.

Source

Thrown at src/cli/handlers/account.ts:276

 * silently would target the laptop rather than the host the user named — the exact
 * mistake this feature exists to avoid. A `--help` note does not reach someone who
 * already typed the flag.
 */
function rejectRemoteSelectionFlags(ctx: HandlerContext, command: string): void {
  for (const flag of ['environment', 'pairing-code']) {
    if (ctx.flags.has(flag)) {
      throw new RuntimeClientError(
        'invalid_argument',
        `\`--${flag}\` does not retarget \`${command}\`. Run it on the host whose accounts you want to manage.`
      )
    }
  }
}

async function assertAccountImportSupported({ client }: HandlerContext): Promise<void> {
  const status = await client.call<RuntimeStatus>('status.get')
  if (!status.result.capabilities?.includes(ACCOUNT_IMPORT_RUNTIME_CAPABILITY)) {
    throw new RuntimeClientError(
      'incompatible_runtime',
      'The running Orca runtime is too old to add accounts from the CLI. Update or restart Orca and try again.'
    )
  }
}

/** CLI handlers for `orca account add [--agent claude|codex]` and `orca account list`. */
export const ACCOUNT_HANDLERS: Record<string, CommandHandler> = {
  'account add': async (ctx) => {
    const agentFlag = ctx.flags.get('agent')
    // Why: a valueless `--agent` parses as boolean true; defaulting it to claude
    // would silently run a full OAuth login for the provider the user did not ask for.
    if (agentFlag !== undefined && typeof agentFlag !== 'string') {
      throw new RuntimeClientError(
        'invalid_argument',
        'Missing a value for --agent. Use `--agent claude` or `--agent codex`.'
      )
    }

View on GitHub (pinned to 1136503c6a)

Solutions

  1. Update Orca to a version whose runtime advertises account-import capability.
  2. Restart the Orca runtime (quit and relaunch the app) so the new binary is actually running.
  3. Confirm you are targeting the expected runtime (not an older remote one).

Example fix

# before: runtime too old
orca account add --agent claude

# after
# 1. update Orca, 2. restart the app, then:
orca account add --agent claude
Defensive patterns

Strategy: validation

Validate before calling

async function runtimeSupportsAccountImport(client: RuntimeClient): Promise<boolean> {
  const status = await client.call<RuntimeStatus>('status.get')
  return !!status.result.capabilities?.includes(ACCOUNT_IMPORT_RUNTIME_CAPABILITY)
}

Type guard

function hasCapability(status: RuntimeStatus, cap: string): boolean {
  return !!status.result.capabilities?.includes(cap)
}

Try / catch

try {
  await assertAccountImportSupported(ctx)
} catch (e) {
  if (e instanceof RuntimeClientError && e.code === 'incompatible_runtime') {
    // prompt user to update + restart Orca, then retry
  }
  throw e
}

Prevention

When it happens

Trigger: status.get().result.capabilities does not include ACCOUNT_IMPORT_RUNTIME_CAPABILITY — typically because the runtime binary is older than the CLI, or the runtime was not restarted after an update.

Common situations: CLI updated but the desktop runtime still running is the previous version; running against a remote/older Orca instance; partial update where only one side rolled forward.

Related errors

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