stablyai/orca · error · Error

${commandLabel} ${args.join(' ')} failed (${result.status}):

Error message

${commandLabel} ${args.join(' ')} failed (${result.status}): ${result.stderr || result.stdout}

What it means

The orca CLI child spawned successfully but exited with a non-zero status (result.status !== 0). The throw surfaces stderr if present, else stdout, so the underlying CLI error message is visible. This is the 'command ran and reported failure' mode — distinct from spawn failure (104) and from an RPC envelope that reports ok=false (106).

Source

Thrown at config/scripts/live-remote-freeze-rpc.mjs:95

    ...args,
    ...(local ? [] : ['--environment', envName]),
    '--json'
  ]

  function orcaJsonSync(args, opts = {}) {
    const started = performance.now()
    const result = spawnSync(cliInvocation.command, commandArgs(args, opts.local), {
      encoding: 'utf8',
      env: cliInvocation.env,
      maxBuffer: MAX_ORCA_RPC_OUTPUT_BYTES,
      timeout: opts.timeoutMs ?? 120_000
    })
    const elapsedMs = performance.now() - started
    if (result.error) {
      throw new Error(`${commandLabel} ${args.join(' ')} failed to start: ${String(result.error)}`)
    }
    if (result.status !== 0) {
      throw new Error(
        `${commandLabel} ${args.join(' ')} failed (${result.status}): ${result.stderr || result.stdout}`
      )
    }
    const parsed = JSON.parse(result.stdout)
    if (parsed.ok === false) {
      throw new Error(`${commandLabel} ${args.join(' ')} ok=false: ${JSON.stringify(parsed)}`)
    }
    return { parsed, elapsedMs, result: parsed.result }
  }

  function orcaJsonAsync(args, opts = {}) {
    const started = performance.now()
    return new Promise((resolve, reject) => {
      const child = spawn(cliInvocation.command, commandArgs(args, opts.local), {
        env: cliInvocation.env,
        stdio: ['ignore', 'pipe', 'pipe']
      })
      let stdout = ''

View on GitHub (pinned to 1136503c6a)

Solutions

Read the embedded stderr/stdout in the message — it is the CLI's own diagnostic and usually names the cause.
Reproduce by running the exact args.join(' ') shown in the message directly in a shell against the same target.
If the status is null the child was killed by a signal; raise opts.timeoutMs or check for OOM/SIGKILL.
For handle/worktree errors, re-list the resource and retry with a current id.

Example fix

// before
if (result.status !== 0) {
  throw new Error(`${commandLabel} ${args.join(' ')} failed (${result.status}): ${result.stderr || result.stdout}`)
}

// after
if (result.status !== 0) {
  const detail = (result.stderr || result.stdout || '').slice(0, 500)
  throw new Error(`${commandLabel} ${args.join(' ')} failed (${result.status}): ${detail}`)
}

Defensive patterns

Strategy: try-catch

Type guard

const isCliFailure = (r) => r && typeof r.status === 'number' && r.status !== 0

Try / catch

try {
  return orcaJsonSync(args)
} catch (e) {
  const m = e.message.match(/failed \((\d+)\):([\s\S]*)/)
  if (m && recoverableStatus(Number(m[1]))) { /* re-list, retry once */ }
  throw e
}

Prevention

Surface the CLI's stderr verbatim in logs — it usually names the cause.
For handle-based commands, re-list the resource and retry once with fresh ids.
Distinguish signal-killed (status null) from real exit codes in retry logic.

When it happens

Trigger: The CLI rejects the arguments (unknown subcommand/flag), the target terminal/worktree does not exist, an auth/permission error, or the CLI hit an internal panic and exited non-zero. Common statuses include 1 (generic), 2 (usage), or a signal-encoded null status.

Common situations: Passing a terminal handle that was already closed, a worktree id that drifted, an orca version that renamed a subcommand, a timeout that surfaces as a non-zero exit, or rate/quota limits enforced by the CLI.

Related errors

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