What causes "native macOS helper app startup was cancelled" in stablyai/orca?

Check the helper crash cause separately — connectMacOSProviderSocket only reports that startup was cancelled, not why.

stablyai/orca · warning · RuntimeClientError

accessibility_error

accessibility_error

Error message

native macOS helper app startup was cancelled

What it means

connectMacOSProviderSocket races repeated connectSocket attempts against a deadline; if the AbortSignal fires first (the transport's catch path aborts on failure, or the outer caller cancelled), it throws RuntimeClientError code 'accessibility_error' with this fixed message. It is the cancellation counterpart to the timeout in 967.

Source

Thrown at src/main/computer/macos-native-provider-socket.ts:23

  socketPath: string,
  timeoutMs: number,
  signal?: AbortSignal
): Promise<net.Socket> {
  const deadline = Date.now() + timeoutMs
  let lastError: Error | null = null
  while (Date.now() < deadline && !signal?.aborted) {
    try {
      return await connectSocket(socketPath, signal)
    } catch (error) {
      lastError = error instanceof Error ? error : new Error(String(error))
      if (signal?.aborted) {
        break
      }
      await sleep(100, signal)
    }
  }
  if (signal?.aborted) {
    throw new RuntimeClientError(
      'accessibility_error',
      'native macOS helper app startup was cancelled'
    )
  }
  throw new RuntimeClientError(
    'action_timeout',
    `native macOS helper app did not open its socket: ${lastError?.message ?? 'timed out'}`
  )
}

function connectSocket(socketPath: string, signal?: AbortSignal): Promise<net.Socket> {
  return new Promise((resolve, reject) => {
    if (signal?.aborted) {
      reject(
        new RuntimeClientError(
          'accessibility_error',
          'native macOS helper app startup was cancelled'
        )

View on GitHub (pinned to 1136503c6a)

Solutions

Check the helper crash cause separately — connectMacOSProviderSocket only reports that startup was cancelled, not why.
If racing startups are expected (concurrent computer-use calls), serialize provider startup through ensureSocketStarted so only one wins.
Retry the computer-use request; the next attempt either starts clean or surfaces the underlying helper error.

Defensive patterns

Strategy: retry

Type guard

import { RuntimeClientError } from './runtime-client-error'

function isHelperStartupCanceled(e: unknown): e is RuntimeClientError {
  return (
    e instanceof RuntimeClientError &&
    e.code === 'accessibility_error' &&
    /startup was cancelled/.test(e.message)
  )
}

Try / catch

try {
  await client.listApps()
} catch (e) {
  if (isHelperStartupCanceled(e)) {
    // transient — retry; if it recurs, investigate the helper crash separately
  } else throw e
}

Prevention

Serialize provider startup through one client instance so concurrent startups do not abort each other.
Treat cancellation as transient and retry the originating computer-use action.
Investigate the helper crash log when cancellation recurs — the cause lives elsewhere.

When it happens

Trigger: The helper process exits/errors while the connect loop is still retrying, so startMacOSNativeProviderSocket's catch aborts the connect promise; or the caller cancelled the overall startup (e.g. a newer provider superseded this one — see 968).

Common situations: Helper crashes during its socket-setup phase; two provider startups racing and the loser is aborted; user-initiated shutdown during the 10s connect window.

Related errors

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