stablyai/orca · critical · RuntimeClientError

orchestration_migration_required

orchestration_migration_required

Error message

The connected Orca runtime does not support the current orchestration contract. No effects were applied.

What it means

Thrown by checkOrchestrationContractCompatibility when the connected Orca runtime's `status.get` response does not advertise the ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY. The CLI and runtime share a versioned orchestration contract; an older runtime cannot honour the current contract, so the CLI aborts before applying any effects. The structured payload (orchestrationMigrationData('runtime_capability_missing')) is attached to guide recovery.

Source

Thrown at src/cli/runtime/client.ts:207

      }
    }
    return getCliStatus(this.userDataPath)
  }

  private async ensureOrchestrationContractCompatible(timeoutMs: number): Promise<void> {
    if (!this.orchestrationContractCheck) {
      this.orchestrationContractCheck = this.checkOrchestrationContractCompatibility(timeoutMs)
    }
    await this.orchestrationContractCheck
  }

  private async checkOrchestrationContractCompatibility(timeoutMs: number): Promise<void> {
    const response = await this.call<RuntimeStatus>('status.get', undefined, { timeoutMs })
    if (this.remotePairing) {
      this.remoteCompat.noteVerifiedStatus(response.result)
    }
    if (!response.result.capabilities?.includes(ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY)) {
      throw new RuntimeClientError(
        'orchestration_migration_required',
        'The connected Orca runtime does not support the current orchestration contract. No effects were applied.',
        orchestrationMigrationData('runtime_capability_missing')
      )
    }
  }

  async openOrca(timeoutMs = 15_000): Promise<RuntimeRpcSuccess<CliStatusResult>> {
    const initial = await this.getCliStatus()
    if (this.remotePairing) {
      return initial
    }

    // Why: a blocked runtime can't open a window, so spawning the app would
    // only hit the single-instance lock and exit — bail before launching.
    if (initial.result.app.desktopWindowStatus === 'blocked') {
      throwDesktopActivationBlocked()
    }

View on GitHub (pinned to 1136503c6a)

Solutions

1. Update the Orca runtime (desktop app or remote server) to a version that advertises the orchestration contract capability, then restart it.
2. Restart the runtime if it was updated but not relaunched.
3. If you cannot update the runtime, downgrade the CLI to a compatible version.

// Pre-flight: fetch runtime status and check the capability before issuing mutations.
const status = await runtimeClient.call('status.get')
if (!status.result.capabilities?.includes(ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY)) {
  throw new Error('Runtime too old; update Orca before running orchestration commands')
}

function runtimeSupportsContract(status: { capabilities?: string[] }): boolean {
  return Boolean(status.capabilities?.includes(ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY))
}

try {
  await runtimeClient.ensureOrchestrationContractCompatible(timeoutMs)
} catch (e) {
  if (e instanceof RuntimeClientError && e.code === 'orchestration_migration_required') {
    // surface upgrade guidance, do not retry mutation
    throw new Error('Orca runtime upgrade required; no effects applied.')
  }
  throw e
}

When it happens

Trigger: Pairing a newer CLI with an older Orca runtime that predates the orchestration contract capability. Connecting to a remote Orca server that has not been updated. Running after an Orca update on the CLI side but not on the runtime/host side.

Common situations: Mixed-version client/host setups (the normal state per the remote wire compatibility contract). CI using a pinned older Orca image. Remote SSH hosts with stale Orca installs. A long-running runtime that was not restarted after an upgrade.

Related errors

• ${result.result.lifecycle.code}
• incompatible_runtime
• invalid_argument
• ${commandLabel} ${args.join(' ')} ok=false: ${JSON.stringify
• A fetch implementation is required.

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