stablyai/orca · error · RuntimeClientError

action_timeout

action_timeout

Error message

native macOS helper app did not open its socket: ${lastError?.message ?? 'timed out'}

What it means

connectMacOSProviderSocket's deadline (HELPER_CONNECT_TIMEOUT_MS, 10s) elapsed and no connectSocket attempt succeeded; the helper never opened its provider.sock. Reported as 'action_timeout' with the last connection error (or 'timed out'). The transport's catch will already have SIGTERM'd the detached helper.

Source

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

  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'
        )
      )
      return
    }
    const socket = net.createConnection(socketPath)
    const cleanup = (): void => {

View on GitHub (pinned to 1136503c6a)

Solutions

1. Retry the computer-use request — many first-run stalls are transient.
2. Inspect Console.app for the helper process (orca-computer-use-macos) for the bind failure or TCC prompt blocking it.
3. Grant Accessibility & Screen Recording to the helper up front via openComputerUsePermissions so first-launch prompts do not block the socket.
4. If reproducing in CI, raise HELPER_CONNECT_TIMEOUT_MS only after ruling out a real hang; otherwise investigate the helper's startup log.

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

function isHelperSocketTimeout(e: unknown): e is RuntimeClientError {
  return (
    e instanceof RuntimeClientError &&
    e.code === 'action_timeout' &&
    /did not open its socket/.test(e.message)
  )
}

try {
  await client.listApps()
} catch (e) {
  if (isHelperSocketTimeout(e)) {
    // one bounded retry; if it persists, escalate — first-launch TCC/Gatekeeper stalls need user action
  } else throw e
}

When it happens

Trigger: Helper spawned but blocked before binding its socket (TCC prompt hanging, slow first-launch signature validation, sandbox denial); socket permission/path mismatch between helper and client; helper silently exiting and respawning under a watchdog without ever binding.

Common situations: First run after install while macOS evaluates notarization/Gatekeeper; heavy system load making the helper's bind exceed 10s; SOCK path under a tmpdir with restrictive perms; security software interposing on Unix sockets.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• accessibility_error
• accessibility_error
• Missing Orca Computer Use helper app at ${helperAppPath}
• Missing signing identity for Orca Computer Use helper app
• invalid_argument

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