{"record":{"id":"45dfd303aba94fab","repo":"stablyai/orca","slug":"runtime-open-failed","errorCode":"runtime_open_failed","errorMessage":"Could not determine how to launch Orca. Start Orca manually and try again.","messagePattern":"Could not determine how to launch Orca\\. Start Orca manually and try again\\.","errorType":"error_code","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/cli/runtime/launch.ts","lineNumber":59,"sourceCode":"      const appBundlePath = getMacAppBundlePath(process.execPath)\n      if (appBundlePath) {\n        // Why: launching the inner MacOS binary directly can trigger macOS app\n        // launch failures and bypass normal bundle lifecycle. The public\n        // packaged CLI should re-open the .app the same way Finder does.\n        spawnDetached('open', [appBundlePath], {\n          env: stripElectronRunAsNode(process.env)\n        })\n        return\n      }\n    }\n\n    spawnDetached(process.execPath, [], {\n      env: stripElectronRunAsNode(process.env)\n    })\n    return\n  }\n\n  throw new RuntimeClientError(\n    'runtime_open_failed',\n    'Could not determine how to launch Orca. Start Orca manually and try again.'\n  )\n}\n\nfunction spawnDetached(command: string, args: string[], options: SpawnOptions): void {\n  const child = spawnProcess(command, args, {\n    detached: true,\n    stdio: 'ignore',\n    ...options\n  })\n  // Why: detached launch errors are reported asynchronously after this function\n  // returns; openOrca already reports the user-facing timeout if startup fails.\n  child.once('error', () => {})\n  child.unref()\n}\n\nexport function serveOrcaApp(","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/cli/runtime/launch.ts#L41-L77","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)."],"exampleFix":"// before (standalone node CLI, no Electron context)\nlaunchOrcaApp()\n// after\nexport ORCA_APP_EXECUTABLE=/Applications/Orca.app/Contents/MacOS/Orca\nlaunchOrcaApp()","handlingStrategy":"try-catch","validationCode":"// Pre-check launch context before calling launchOrcaApp.\nconst canAutoLaunch =\n  !!process.env.ORCA_OPEN_COMMAND?.trim() ||\n  !!process.env.ORCA_APP_EXECUTABLE?.trim() ||\n  process.env.ELECTRON_RUN_AS_NODE === '1'\nif (!canAutoLaunch) throw new Error('No launch path; set ORCA_APP_EXECUTABLE or start Orca manually')","typeGuard":"function canDetermineLaunchPath(): boolean {\n  return (\n    !!process.env.ORCA_OPEN_COMMAND?.trim() ||\n    !!process.env.ORCA_APP_EXECUTABLE?.trim() ||\n    process.env.ELECTRON_RUN_AS_NODE === '1'\n  )\n}","tryCatchPattern":"try {\n  launchOrcaApp()\n} catch (e) {\n  if (e instanceof RuntimeClientError && e.code === 'runtime_open_failed') {\n    // prompt user to start Orca manually, or set ORCA_APP_EXECUTABLE and retry\n  } else throw e\n}","preventionTips":["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."],"tags":["runtime","launch","electron","environment","config"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}