stablyai/orca · error · RuntimeClientError

runtime_open_failed

runtime_open_failed

Error message

Could not determine how to launch Orca. Start Orca manually and try again.

What it means

Thrown by launchOrcaApp when none of the launch-determination branches succeed: no ORCA_OPEN_COMMAND override, no ORCA_APP_EXECUTABLE override, and not running under ELECTRON_RUN_AS_NODE (so the macOS bundle path, execPath, and ELECTRON_RUN_AS_NODE fallbacks all miss). The CLI cannot guess how to start the app, so it errors and asks the user to start it manually.

Source

Thrown at src/cli/runtime/launch.ts:59

      const appBundlePath = getMacAppBundlePath(process.execPath)
      if (appBundlePath) {
        // Why: launching the inner MacOS binary directly can trigger macOS app
        // launch failures and bypass normal bundle lifecycle. The public
        // packaged CLI should re-open the .app the same way Finder does.
        spawnDetached('open', [appBundlePath], {
          env: stripElectronRunAsNode(process.env)
        })
        return
      }
    }

    spawnDetached(process.execPath, [], {
      env: stripElectronRunAsNode(process.env)
    })
    return
  }

  throw new RuntimeClientError(
    'runtime_open_failed',
    'Could not determine how to launch Orca. Start Orca manually and try again.'
  )
}

function spawnDetached(command: string, args: string[], options: SpawnOptions): void {
  const child = spawnProcess(command, args, {
    detached: true,
    stdio: 'ignore',
    ...options
  })
  // Why: detached launch errors are reported asynchronously after this function
  // returns; openOrca already reports the user-facing timeout if startup fails.
  child.once('error', () => {})
  child.unref()
}

export function serveOrcaApp(

View on GitHub (pinned to 1136503c6a)

Solutions

Start the Orca desktop app manually from your launcher, then retry the CLI command.
Set ORCA_APP_EXECUTABLE to the Orca Electron binary path, or ORCA_OPEN_COMMAND to a custom launch command.
Reinstall Orca so the CLI runs inside the Electron bundle (ELECTRON_RUN_AS_NODE path).

Example fix

// before (standalone node CLI, no Electron context)
launchOrcaApp()
// after
export ORCA_APP_EXECUTABLE=/Applications/Orca.app/Contents/MacOS/Orca
launchOrcaApp()

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check launch context before calling launchOrcaApp.
const canAutoLaunch =
  !!process.env.ORCA_OPEN_COMMAND?.trim() ||
  !!process.env.ORCA_APP_EXECUTABLE?.trim() ||
  process.env.ELECTRON_RUN_AS_NODE === '1'
if (!canAutoLaunch) throw new Error('No launch path; set ORCA_APP_EXECUTABLE or start Orca manually')

Type guard

function canDetermineLaunchPath(): boolean {
  return (
    !!process.env.ORCA_OPEN_COMMAND?.trim() ||
    !!process.env.ORCA_APP_EXECUTABLE?.trim() ||
    process.env.ELECTRON_RUN_AS_NODE === '1'
  )
}

Try / catch

try {
  launchOrcaApp()
} catch (e) {
  if (e instanceof RuntimeClientError && e.code === 'runtime_open_failed') {
    // prompt user to start Orca manually, or set ORCA_APP_EXECUTABLE and retry
  } else throw e
}

Prevention

Set ORCA_APP_EXECUTABLE or ORCA_OPEN_COMMAND in environments where the CLI is not the Electron bundle.
Ensure the CLI install includes the Electron runtime for auto-launch to work.

When it happens

Trigger: Calling launchOrcaApp from a context where process.execPath is not an Electron binary, ELECTRON_RUN_AS_NODE is unset, and no override env vars are set. Common with a standalone Node-based CLI install that is not the Orca Electron bundle.

Common situations: Running a globally-installed Orca CLI built on plain Node. CI/containers without the Electron app present. A misconfigured install where ORCA_APP_EXECUTABLE points at a missing path. Packaging that strips the Electron context.

Related errors

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