stablyai/orca · error · RuntimeClientError

incompatible_runtime

incompatible_runtime

Error message

The connected Orca runtime does not support worker model or effort overrides. Update or restart Orca and try again.

What it means

Thrown in 'orchestration worker-start' (line 863) when --model or --effort is passed but the connected runtime does not advertise the ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY in its status.get capabilities list (lines 856-862). This is a capability negotiation failure: the worker-launch-preferences feature is newer than the runtime, so the CLI refuses to send overrides the runtime would silently ignore or misinterpret.

Source

Thrown at src/cli/handlers/orchestration.ts:863

        result: getOptionalStringFlag(flags, 'result'),
        run: getOptionalStringFlag(flags, 'run'),
        callerTerminalHandle: await resolveCoordinatorTerminalHandle(flags, cwd, client)
      }
    )
    printResult(result, json, (r) => `Updated ${r.task.id} -> ${r.task.status}`)
  },

  'orchestration worker-start': async ({ flags, client, cwd, json }) => {
    const model = getOptionalStringFlag(flags, 'model')
    const effort = getOptionalStringFlag(flags, 'effort')
    if (model || effort) {
      const status = await client.call<RuntimeStatus>('status.get')
      if (
        !status.result.capabilities?.includes(
          ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY
        )
      ) {
        throw new RuntimeClientError(
          'incompatible_runtime',
          'The connected Orca runtime does not support worker model or effort overrides. Update or restart Orca and try again.'
        )
      }
    }
    const result = await callMutation<{
      runId: string
      taskId: string
      dispatchId: string
      state: string
      failedStage?: string
      lastError?: string
      warning?: string
      effects: unknown[]
      residualResources: unknown[]
    }>(client, flags, 'orchestration.workerStart', {
      task: getRequiredStringFlag(flags, 'task'),
      on: getOptionalStringFlag(flags, 'on'),

View on GitHub (pinned to 1136503c6a)

Solutions

Update or restart Orca to a runtime version that supports worker model/effort overrides.
Drop --model and --effort to launch the worker with the runtime's defaults until you upgrade.
Verify the capability with 'orca status' (or status.get) and confirm ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY is listed.

Example fix

// before
orca orchestration worker-start --task t1 --model gpt-x   (runtime lacks capability)
// after
orca orchestration worker-start --task t1   # use runtime defaults until upgraded

Defensive patterns

Strategy: fallback

Validate before calling

const status = await client.call('status.get')
const supportsPrefs = status.result.capabilities?.includes(ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY)
if ((model || effort) && !supportsPrefs) {
  // drop --model/--effort or abort with a clear message before worker-start
}

Type guard

function runtimeSupportsWorkerLaunchPrefs(status: { result: { capabilities?: string[] } }): boolean {
  return !!status.result.capabilities?.includes(ORCHESTRATION_WORKER_LAUNCH_PREFERENCES_RUNTIME_CAPABILITY)
}

Try / catch

try {
  await runWorkerStart(['--model', m])
} catch (err) {
  if (err instanceof RuntimeClientError && err.code === 'incompatible_runtime') {
    // retry worker-start without --model/--effort using runtime defaults
  } else { throw err }
}

Prevention

Keep client and runtime versions aligned.
Gate --model/--effort behind a capability check when targeting mixed runtimes.
Run 'orca status' after upgrades to confirm capabilities are advertised.

When it happens

Trigger: Calling 'orchestration worker-start --model <m>' or '--effort <e>' against a runtime whose status.get response lacks the worker-launch-preferences capability string. Checked via client.call('status.get') then capabilities?.includes(...).

Common situations: Client newer than the runtime after a partial upgrade; connecting to an older remote Orca server; runtime restarted with an older binary still in PATH; side-loaded runtime without the feature flag.

Related errors

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