{"record":{"id":"8e54c54d84fda6e2","repo":"stablyai/orca","slug":"orchestration-migration-required-8e54c5","errorCode":"orchestration_migration_required","errorMessage":"The connected Orca runtime does not support the current orchestration contract. No effects were applied.","messagePattern":"The connected Orca runtime does not support the current orchestration contract\\. No effects were applied\\.","errorType":"error_code","errorClass":"RuntimeClientError","httpStatus":null,"severity":"critical","filePath":"src/cli/runtime/client.ts","lineNumber":207,"sourceCode":"      }\n    }\n    return getCliStatus(this.userDataPath)\n  }\n\n  private async ensureOrchestrationContractCompatible(timeoutMs: number): Promise<void> {\n    if (!this.orchestrationContractCheck) {\n      this.orchestrationContractCheck = this.checkOrchestrationContractCompatibility(timeoutMs)\n    }\n    await this.orchestrationContractCheck\n  }\n\n  private async checkOrchestrationContractCompatibility(timeoutMs: number): Promise<void> {\n    const response = await this.call<RuntimeStatus>('status.get', undefined, { timeoutMs })\n    if (this.remotePairing) {\n      this.remoteCompat.noteVerifiedStatus(response.result)\n    }\n    if (!response.result.capabilities?.includes(ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY)) {\n      throw new RuntimeClientError(\n        'orchestration_migration_required',\n        'The connected Orca runtime does not support the current orchestration contract. No effects were applied.',\n        orchestrationMigrationData('runtime_capability_missing')\n      )\n    }\n  }\n\n  async openOrca(timeoutMs = 15_000): Promise<RuntimeRpcSuccess<CliStatusResult>> {\n    const initial = await this.getCliStatus()\n    if (this.remotePairing) {\n      return initial\n    }\n\n    // Why: a blocked runtime can't open a window, so spawning the app would\n    // only hit the single-instance lock and exit — bail before launching.\n    if (initial.result.app.desktopWindowStatus === 'blocked') {\n      throwDesktopActivationBlocked()\n    }","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/cli/runtime/client.ts#L189-L225","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Update the Orca runtime (desktop app or remote server) to a version that advertises the orchestration contract capability, then restart it.","Restart the runtime if it was updated but not relaunched.","If you cannot update the runtime, downgrade the CLI to a compatible version."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Pre-flight: fetch runtime status and check the capability before issuing mutations.\nconst status = await runtimeClient.call('status.get')\nif (!status.result.capabilities?.includes(ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY)) {\n  throw new Error('Runtime too old; update Orca before running orchestration commands')\n}","typeGuard":"function runtimeSupportsContract(status: { capabilities?: string[] }): boolean {\n  return Boolean(status.capabilities?.includes(ORCHESTRATION_CONTRACT_RUNTIME_CAPABILITY))\n}","tryCatchPattern":"try {\n  await runtimeClient.ensureOrchestrationContractCompatible(timeoutMs)\n} catch (e) {\n  if (e instanceof RuntimeClientError && e.code === 'orchestration_migration_required') {\n    // surface upgrade guidance, do not retry mutation\n    throw new Error('Orca runtime upgrade required; no effects applied.')\n  }\n  throw e\n}","preventionTips":["Keep CLI and runtime versions in lockstep; update both together.","In remote setups, version-check the host runtime before dispatching orchestration calls."],"tags":["runtime","orchestration","version-mismatch","remote","capability"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}