{"record":{"id":"287ae5d25c71c814","repo":"stablyai/orca","slug":"desktop-activation-blocked","errorCode":"desktop_activation_blocked","errorMessage":"Orca is running headlessly, but it cannot open a desktop window safely because the persistent terminal provider is unavailable. Quit Orca normally and start the app again; do not use open -n.","messagePattern":"Orca is running headlessly, but it cannot open a desktop window safely because the persistent terminal provider is unavailable\\. Quit Orca normally and start the app again; do not use open -n\\.","errorType":"error_code","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/cli/runtime/client.ts","lineNumber":265,"sourceCode":"  }\n}\n\nfunction attachMutationRecovery(error: unknown, requestId: string | undefined): unknown {\n  if (!requestId || !(error instanceof RuntimeClientError)) {\n    return error\n  }\n  return new RuntimeClientError(\n    error.code,\n    `${error.message} Orchestration mutation request ID: ${requestId}.`,\n    {\n      ...(error.data && typeof error.data === 'object' ? error.data : {}),\n      orchestrationRequestId: requestId\n    }\n  )\n}\n\nfunction throwDesktopActivationBlocked(): never {\n  throw new RuntimeClientError(\n    'desktop_activation_blocked',\n    'Orca is running headlessly, but it cannot open a desktop window safely because the persistent terminal provider is unavailable. Quit Orca normally and start the app again; do not use open -n.'\n  )\n}\n\nfunction resolveRemotePairing(\n  userDataPath: string,\n  pairingCode: string | null,\n  environmentSelector: string | null\n): PairingOffer | null {\n  if (pairingCode && environmentSelector) {\n    throw new RuntimeClientError(\n      'invalid_argument',\n      'Use either --pairing-code or --environment, not both.'\n    )\n  }\n  if (environmentSelector) {\n    return resolveEnvironmentPairingOffer(userDataPath, environmentSelector)","sourceCodeStart":247,"sourceCodeEnd":283,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/cli/runtime/client.ts#L247-L283","documentation":"Thrown by throwDesktopActivationBlocked when the polled desktop window status is 'blocked'. This specifically means Orca is running headlessly AND the persistent terminal provider required to safely open a desktop window is unavailable. Opening a window anyway (e.g. via `open -n`) risks instability, so the CLI refuses and instructs the user to restart Orca normally. It is raised inside the openOrca polling loop.","triggerScenarios":"Calling openOrca while Orca was launched headlessly (e.g. via `serve` or a non-standard launcher) and the persistent terminal provider is missing or disabled, causing status.result.app.desktopWindowStatus === 'blocked'.","commonSituations":"Using `open -n` to force a second Orca instance on macOS. Running Orca in a container or detached mode without the terminal provider. A previous abnormal exit leaving Orca in a headless-without-provider state.","solutions":["Quit Orca completely (Cmd+Q / proper exit) and start the app again normally from the launcher.","Do NOT use `open -n` or other force-new-instance launches.","If you need headless operation, use the dedicated serve/headless mode instead of requesting a desktop window."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Best-effort preflight: detect headless-without-provider state.\nconst status = await runtimeClient.getCliStatus()\nif (status.result.app.desktopWindowStatus === 'blocked') {\n  throw new Error('Desktop activation blocked; restart Orca normally (not open -n)')\n}","typeGuard":"function desktopActivationBlocked(status: { app: { desktopWindowStatus: string } }): boolean {\n  return status.app.desktopWindowStatus === 'blocked'\n}","tryCatchPattern":"try {\n  await runtimeClient.openOrca()\n} catch (e) {\n  if (e instanceof RuntimeClientError && e.code === 'desktop_activation_blocked') {\n    // instruct user to quit and restart Orca normally; do not auto-retry with open -n\n  } else throw e\n}","preventionTips":["Never launch Orca with `open -n` or other force-new-instance methods.","Quit Orca cleanly (Cmd+Q) and relaunch from the launcher when window activation fails.","Use serve/headless mode if you do not need a GUI."],"tags":["runtime","desktop-window","headless","terminal-provider","macos"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}