stablyai/orca · warning · RuntimeClientError

unsupported_capability

unsupported_capability

Error message

native macOS provider does not support ${String(group)}.${capability}

What it means

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.

Source

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

      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(
      'unsupported_capability',
      `native macOS provider does not support ${String(group)}.${capability}`
    )
  }
  private async ensureActionSupported(method: NativeActionMethod): Promise<void> {
    await this.ensureCapability('actions', macOSActionCapabilityKey(method))
  }
  private async ensureSocketStarted(helperExecutablePath: string): Promise<net.Socket> {
    if (this.socket && !this.socket.destroyed) {
      return this.socket
    }
    this.cleanupActiveSocketListeners()
    this.socket = null
    if (this.socketStartPromise) {
      return await this.socketStartPromise
    }
    const socketStartPromise = this.startSocket(helperExecutablePath)
    this.socketStartPromise = socketStartPromise

View on GitHub (pinned to 1136503c6a)

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).

Example fix

// before: unconditional call
await client.action('drag', params)

// after: gate on advertised capabilities
const caps = await client.capabilities()
if (assertMacOSProviderCapability(caps, 'actions', 'drag')) {
  await client.action('drag', params)
} else {
  // degrade to click-move-click or surface 'not supported' to the user
}

Defensive patterns

Strategy: type-guard

Validate before calling

const caps = await client.capabilities()
if (!assertMacOSProviderCapability(caps, 'actions', macOSActionCapabilityKey(method))) {
  // skip the call; degrade or surface 'not supported'
}

Type guard

import { assertMacOSProviderCapability } from './macos-native-provider-contract'
import type { ComputerProviderCapabilities } from '../../shared/runtime-types'

function supportsAction(
  caps: ComputerProviderCapabilities,
  method: NativeActionMethod
): boolean {
  return assertMacOSProviderCapability(caps, 'actions', macOSActionCapabilityKey(method))
}

Try / catch

try {
  await client.action(method, params)
} catch (e) {
  if (e instanceof RuntimeClientError && e.code === 'unsupported_capability') {
    // fall back to a supported equivalent or surface to the user
  } else throw e
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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