{"record":{"id":"bdb1b864600c3b82","repo":"stablyai/orca","slug":"unsupported-capability-bdb1b8","errorCode":"unsupported_capability","errorMessage":"native macOS provider does not support ${String(group)}.${capability}","messagePattern":"native macOS provider does not support (.+?)\\.(.+?)","errorType":"error_code","errorClass":"RuntimeClientError","httpStatus":null,"severity":"warning","filePath":"src/main/computer/macos-native-provider-client.ts","lineNumber":162,"sourceCode":"      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(\n      'unsupported_capability',\n      `native macOS provider does not support ${String(group)}.${capability}`\n    )\n  }\n  private async ensureActionSupported(method: NativeActionMethod): Promise<void> {\n    await this.ensureCapability('actions', macOSActionCapabilityKey(method))\n  }\n  private async ensureSocketStarted(helperExecutablePath: string): Promise<net.Socket> {\n    if (this.socket && !this.socket.destroyed) {\n      return this.socket\n    }\n    this.cleanupActiveSocketListeners()\n    this.socket = null\n    if (this.socketStartPromise) {\n      return await this.socketStartPromise\n    }\n    const socketStartPromise = this.startSocket(helperExecutablePath)\n    this.socketStartPromise = socketStartPromise","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/computer/macos-native-provider-client.ts#L144-L180","documentation":"ensureCapability calls assertMacOSProviderCapability against the provider's handshake capabilities (supports.<group>.<capability>); when the helper does not advertise the requested pair (e.g. actions.drag, windows.list), the call throws 'unsupported_capability'. This is a deliberate preflight so unsupported actions never reach the socket.","triggerScenarios":"Calling listWindows when supports.windows.list is false; calling a newer action (e.g. setValue, hotkey) against a helper built before that action was added; calling an action the helper deliberately omits on a given macOS version.","commonSituations":"Mixed-version helper (see 964); asking for a macOS-15-only capability on macOS 14; a feature flag disabling an action in the helper build; client code that did not gate on capabilities() before issuing the action.","solutions":["Call capabilities() once and gate the UI/codepath on supports.<group>.<capability> before invoking the action.","Upgrade the helper to a build that advertises the capability, or fall back to a supported equivalent (e.g. typeText instead of setValue).","Confirm the capability key spelling matches what the helper publishes (macOSActionCapabilityKey maps method names to keys)."],"exampleFix":"// before: unconditional call\nawait client.action('drag', params)\n\n// after: gate on advertised capabilities\nconst caps = await client.capabilities()\nif (assertMacOSProviderCapability(caps, 'actions', 'drag')) {\n  await client.action('drag', params)\n} else {\n  // degrade to click-move-click or surface 'not supported' to the user\n}","handlingStrategy":"type-guard","validationCode":"const caps = await client.capabilities()\nif (!assertMacOSProviderCapability(caps, 'actions', macOSActionCapabilityKey(method))) {\n  // skip the call; degrade or surface 'not supported'\n}","typeGuard":"import { assertMacOSProviderCapability } from './macos-native-provider-contract'\nimport type { ComputerProviderCapabilities } from '../../shared/runtime-types'\n\nfunction supportsAction(\n  caps: ComputerProviderCapabilities,\n  method: NativeActionMethod\n): boolean {\n  return assertMacOSProviderCapability(caps, 'actions', macOSActionCapabilityKey(method))\n}","tryCatchPattern":"try {\n  await client.action(method, params)\n} catch (e) {\n  if (e instanceof RuntimeClientError && e.code === 'unsupported_capability') {\n    // fall back to a supported equivalent or surface to the user\n  } else throw e\n}","preventionTips":["Fetch capabilities() once at provider startup and cache it for the session.","Gate UI affordances on the advertised supports map so unsupported actions are never offered.","Re-fetch capabilities after a provider restart — the helper build may have changed."],"tags":["macos","computer-use","capabilities","unsupported","provider"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}