stablyai/orca · error · RuntimeClientError

desktop_activation_blocked

desktop_activation_blocked

Error message

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.

What it means

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.

Source

Thrown at src/cli/runtime/client.ts:265

  }
}

function attachMutationRecovery(error: unknown, requestId: string | undefined): unknown {
  if (!requestId || !(error instanceof RuntimeClientError)) {
    return error
  }
  return new RuntimeClientError(
    error.code,
    `${error.message} Orchestration mutation request ID: ${requestId}.`,
    {
      ...(error.data && typeof error.data === 'object' ? error.data : {}),
      orchestrationRequestId: requestId
    }
  )
}

function throwDesktopActivationBlocked(): never {
  throw new RuntimeClientError(
    'desktop_activation_blocked',
    '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.'
  )
}

function resolveRemotePairing(
  userDataPath: string,
  pairingCode: string | null,
  environmentSelector: string | null
): PairingOffer | null {
  if (pairingCode && environmentSelector) {
    throw new RuntimeClientError(
      'invalid_argument',
      'Use either --pairing-code or --environment, not both.'
    )
  }
  if (environmentSelector) {
    return resolveEnvironmentPairingOffer(userDataPath, environmentSelector)

View on GitHub (pinned to 1136503c6a)

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.

Defensive patterns

Strategy: try-catch

Validate before calling

// Best-effort preflight: detect headless-without-provider state.
const status = await runtimeClient.getCliStatus()
if (status.result.app.desktopWindowStatus === 'blocked') {
  throw new Error('Desktop activation blocked; restart Orca normally (not open -n)')
}

Type guard

function desktopActivationBlocked(status: { app: { desktopWindowStatus: string } }): boolean {
  return status.app.desktopWindowStatus === 'blocked'
}

Try / catch

try {
  await runtimeClient.openOrca()
} catch (e) {
  if (e instanceof RuntimeClientError && e.code === 'desktop_activation_blocked') {
    // instruct user to quit and restart Orca normally; do not auto-retry with open -n
  } else throw e
}

Prevention

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.

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

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