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.

Solutions

1. Start the Orca desktop app manually from your launcher, then retry the CLI command.
2. Set ORCA_APP_EXECUTABLE to the Orca Electron binary path, or ORCA_OPEN_COMMAND to a custom launch command.
3. 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()

// 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')

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

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
}

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

• Electron builds are not available on platform
• Expected a positive integer, got
• GITHUB_REPOSITORY must be in owner/repo form, got
• ORCA_ELECTRON_PACKAGE_RETRY_DELAYS_MS must contain…
• A fetch implementation is required.

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

Appendix: 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)