{"record":{"id":"cd7ea6778f80b041","repo":"stablyai/orca","slug":"provider-incompatible","errorCode":"provider_incompatible","errorMessage":"native macOS provider protocol ${restarted.protocolVersion} is incompatible with required protocol ${REQUIRED_MACOS_PROVIDER_PROTOCOL_VERSION}","messagePattern":"native macOS provider protocol (.+?) is incompatible with required protocol (.+?)","errorType":"error_code","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/main/computer/macos-native-provider-client.ts","lineNumber":144,"sourceCode":"      }\n      this.invalidateActiveSocketAfterWriteFailure(transport, wrapped)\n      throw wrapped\n    }\n    return await result\n  }\n  private async ensureCompatible(): Promise<void> {\n    if (this.providerCapabilities) {\n      return\n    }\n    const capabilities = await this.readCapabilities()\n    if (capabilities.protocolVersion === REQUIRED_MACOS_PROVIDER_PROTOCOL_VERSION) {\n      this.providerCapabilities = capabilities\n      return\n    }\n    this.shutdown()\n    const restarted = await this.readCapabilities()\n    if (restarted.protocolVersion !== REQUIRED_MACOS_PROVIDER_PROTOCOL_VERSION) {\n      throw new RuntimeClientError(\n        'provider_incompatible',\n        `native macOS provider protocol ${restarted.protocolVersion} is incompatible with required protocol ${REQUIRED_MACOS_PROVIDER_PROTOCOL_VERSION}`\n      )\n    }\n    this.providerCapabilities = restarted\n  }\n  private async readCapabilities(): Promise<ComputerProviderCapabilities> {\n    return (await this.send('handshake', {})) as ComputerProviderCapabilities\n  }\n  private async ensureCapability(\n    group: keyof ComputerProviderCapabilities['supports'],\n    capability: string\n  ): Promise<void> {\n    await this.ensureCompatible()\n    if (assertMacOSProviderCapability(this.providerCapabilities, group, capability)) {\n      return\n    }\n    throw new RuntimeClientError(","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/computer/macos-native-provider-client.ts#L126-L162","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"import { RuntimeClientError } from './runtime-client-error'\n\nfunction isProviderIncompatible(e: unknown): e is RuntimeClientError {\n  return e instanceof RuntimeClientError && e.code === 'provider_incompatible'\n}","tryCatchPattern":"try {\n  await client.capabilities()\n} catch (e) {\n  if (isProviderIncompatible(e)) {\n    // prompt rebuild/reinstall of the helper; do NOT retry — version skew is deterministic\n  } else throw e\n}","preventionTips":["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."],"tags":["macos","computer-use","version-skew","protocol","provider","handshake"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}