stablyai/orca · info · RuntimeClientError

accessibility_error

accessibility_error

Error message

native macOS provider startup was superseded

What it means

startMacOSNativeProviderSocket won the connect race but its isCurrent() callback returned false — meaning a newer startSocket call incremented socketStartGeneration (or chose a different socketPath) while this one was in flight. The connected socket is destroyed, the scratch directory cleaned, and the older startup throws 'accessibility_error' so its caller does not bind to a stale transport.

Source

Thrown at src/main/computer/macos-native-provider-transport.ts:94

  const socketToken = randomUUID()
  const socketTokenPath = join(socketDirectory, 'provider.token')
  writeFileSync(socketTokenPath, socketToken, { encoding: 'utf8', mode: 0o600 })
  // Why: launching the nested helper via LaunchServices can make TCC evaluate
  // Orca.app as responsible; the signed helper executable owns this grant.
  const provider = spawnProvider(helperExecutablePath, socketPath, socketTokenPath)
  const providerFailure = waitForProviderLaunchFailure(provider)
  const connectAbort = new AbortController()
  try {
    const socket = await Promise.race([
      connectMacOSProviderSocket(socketPath, HELPER_CONNECT_TIMEOUT_MS, connectAbort.signal),
      providerFailure.promise
    ])
    providerFailure.cleanup()
    rmSync(socketTokenPath, { force: true })
    if (!isCurrent(socketPath)) {
      socket.destroy()
      cleanupSocketDirectory(socketDirectory)
      throw new RuntimeClientError(
        'accessibility_error',
        'native macOS provider startup was superseded'
      )
    }
    return { socket, socketDirectory, socketPath, socketToken }
  } catch (error) {
    connectAbort.abort()
    providerFailure.cleanup()
    // Why: connect failures happen after spawn; terminate the detached helper
    // so repeated startup attempts do not leave orphan providers.
    provider.kill('SIGTERM')
    if (isCurrent(socketPath)) {
      cleanupSocketDirectory(socketDirectory)
    }
    throw error
  }
}

View on GitHub (pinned to 1136503c6a)

Solutions

1. Route all provider calls through a single client instance so ensureSocketStarted dedupes via socketStartPromise.
2. Treat 'native macOS provider startup was superseded' as a transient signal — retry the originating action; the winning startup is already serving.
3. Avoid calling client.shutdown() then immediately issuing actions without awaiting the spawn cycle.

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

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

try {
  await client.listApps()
} catch (e) {
  if (isStartupSuperseded(e)) {
    // benign — the winning startup is already serving; retry once
  } else throw e
}

When it happens

Trigger: Two concurrent provider startups interleave (e.g. shutdown followed immediately by a new call, or two actions racing before socketStartPromise is set); a timed-out startup finally connects after its replacement already took over.

Common situations: Concurrent computer-use calls when socketStartPromise has not yet been cached; rapid shutdown()/call() sequences in tests; an old connect retry delivering after a manual shutdown.

Related errors

• accessibility_error
• action_timeout
• 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/3fbbfd3ae6234592. Report an issue: GitHub.