stablyai/orca · error · Error

${commandLabel} ${args.join(' ')} failed to start: ${String(

Error message

${commandLabel} ${args.join(' ')} failed to start: ${String(result.error)}

What it means

orcaJsonSync spawns the orca CLI via spawnSync and inspects result.error, which Node sets when the child could not be spawned at all (ENOENT, EACCES, bad executable path). This throw fires before any exit code or stdout is available because the process never ran. It is the 'binary unreachable' failure mode distinct from a non-zero exit (105) or an RPC-level ok=false (106).

Source

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

  const commandLabel = cliCommand ?? resolveOrcaCliCommand({ env, platform })
  const commandArgs = (args, local) => [
    ...cliInvocation.prefixArgs,
    ...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,

View on GitHub (pinned to 1136503c6a)

Solutions

Confirm the binary exists and is executable: test -x "$(command -v orca)" or check cliInvocation.command directly.
Print cliInvocation.command and cliInvocation.env.PATH to verify the spawn target and search path.
Reinstall/rebuild orca so the path the script resolves matches an on-disk executable.
If running remotely over SSH, ensure the binary is on PATH on the remote host, not just locally.

Example fix

// before
const result = spawnSync(cliInvocation.command, args, { env: cliInvocation.env })
if (result.error) throw new Error(`${commandLabel} ... failed to start: ${result.error}`)

// after
const { existsSync } = require('node:fs')
if (!cliInvocation.command || !existsSync(cliInvocation.command.split(' ')[0])) {
  throw new Error(`orca binary not found at ${cliInvocation.command}`)
}
const result = spawnSync(cliInvocation.command, args, { env: cliInvocation.env })
if (result.error) throw new Error(`${commandLabel} ... failed to start: ${result.error}`)

Defensive patterns

Strategy: validation

Validate before calling

const { existsSync } = require('node:fs')
const bin = cliInvocation.command
if (!bin || !(existsSync(bin) || which.sync(bin, { nothrow: true }))) {
  throw new Error(`orca binary not resolvable: ${bin}`)
}

Type guard

const isExecutableTarget = (c) => typeof c === 'string' && c.length > 0

Try / catch

try {
  return orcaJsonSync(args)
} catch (e) {
  if (/failed to start/.test(e.message)) { await ensureOrcaInstalled(); return orcaJsonSync(args) }
  throw e
}

Prevention

Resolve the orca binary path once at startup and validate it is executable.
Keep cliInvocation.env.PATH aligned with the install location.
In remote/SSH runs, verify the binary is on PATH on the remote host.

When it happens

Trigger: cliInvocation.command points at an orca binary that does not exist at that path, lacks the executable bit, is the wrong platform/architecture, or the spawn env (cliInvocation.env) is missing PATH entries needed to locate it.

Common situations: Running the script on a machine without orca installed or built, a stale cliInvocation resolved from a moved install directory, an SSH/remote target where the binary path is relative to the wrong cwd, or a packaging issue where the binary was not bundled.

Related errors

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