stablyai/orca · error · RuntimeClientError

provider_incompatible

provider_incompatible

Error message

native macOS provider protocol ${restarted.protocolVersion} is incompatible with required protocol ${REQUIRED_MACOS_PROVIDER_PROTOCOL_VERSION}

What it means

ensureCompatible() handshakes the native macOS provider, and if the reported protocolVersion does not equal REQUIRED_MACOS_PROVIDER_PROTOCOL_VERSION it shuts the socket down, handshakes once more, and on a second mismatch throws 'provider_incompatible'. This means the running helper executable speaks a different protocol generation than the host client expects — a version skew between Orca and its bundled helper.

Source

Thrown at src/main/computer/macos-native-provider-client.ts:144

      }
      this.invalidateActiveSocketAfterWriteFailure(transport, wrapped)
      throw wrapped
    }
    return await result
  }
  private async ensureCompatible(): Promise<void> {
    if (this.providerCapabilities) {
      return
    }
    const capabilities = await this.readCapabilities()
    if (capabilities.protocolVersion === REQUIRED_MACOS_PROVIDER_PROTOCOL_VERSION) {
      this.providerCapabilities = capabilities
      return
    }
    this.shutdown()
    const restarted = await this.readCapabilities()
    if (restarted.protocolVersion !== REQUIRED_MACOS_PROVIDER_PROTOCOL_VERSION) {
      throw new RuntimeClientError(
        'provider_incompatible',
        `native macOS provider protocol ${restarted.protocolVersion} is incompatible with required protocol ${REQUIRED_MACOS_PROVIDER_PROTOCOL_VERSION}`
      )
    }
    this.providerCapabilities = restarted
  }
  private async readCapabilities(): Promise<ComputerProviderCapabilities> {
    return (await this.send('handshake', {})) as ComputerProviderCapabilities
  }
  private async ensureCapability(
    group: keyof ComputerProviderCapabilities['supports'],
    capability: string
  ): Promise<void> {
    await this.ensureCompatible()
    if (assertMacOSProviderCapability(this.providerCapabilities, group, capability)) {
      return
    }
    throw new RuntimeClientError(

View on GitHub (pinned to 1136503c6a)

Solutions

Rebuild the helper: `pnpm build:computer-macos` so the executable's protocolVersion matches the host's REQUIRED_MACOS_PROVIDER_PROTOCOL_VERSION.
Unset ORCA_COMPUTER_MACOS_HELPER_APP_PATH so Orca resolves the packaged (matched) helper instead of a stale dev build.
Reinstall Orca from a single coherent build so host and helper ship together.
If developing the protocol itself, bump the constant on both sides in the same commit and rebuild.

Defensive patterns

Strategy: try-catch

Type guard

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

function isProviderIncompatible(e: unknown): e is RuntimeClientError {
  return e instanceof RuntimeClientError && e.code === 'provider_incompatible'
}

Try / catch

try {
  await client.capabilities()
} catch (e) {
  if (isProviderIncompatible(e)) {
    // prompt rebuild/reinstall of the helper; do NOT retry — version skew is deterministic
  } else throw e
}

Prevention

Ship host and helper from a single coherent build.
Bump REQUIRED_MACOS_PROVIDER_PROTOCOL_VERSION on both sides atomically.
Unset ORCA_COMPUTER_MACOS_HELPER_APP_PATH in CI to avoid testing against stale dev helpers.

When it happens

Trigger: An Orca upgrade that bumped REQUIRED_MACOS_PROVIDER_PROTOCOL_VERSION while the on-disk helper .app is from an older build; a dev worktree where the host code is newer than native/computer-use-macos/.build; running a packaged Orca against a leftover dev-built helper via ORCA_COMPUTER_MACOS_HELPER_APP_PATH.

Common situations: Mixed old/new binaries on the same machine after a partial upgrade; pulling latest main and forgetting to rebuild the native target; CI matrix where the helper artifact is cached across a protocol bump.

Related errors

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