stablyai/orca · error · RuntimeClientError

orchestration_migration_required

orchestration_migration_required

Error message

The legacy automatic coordinator command is retired. No effects were applied.

What it means

Thrown unconditionally by the 'orchestration coordinator-start' handler (lines 1207-1213). The command is retired: the legacy automatic coordinator has been replaced by the Run/Dispatch/task model, so invoking it always errors with orchestration_migration_required and no effects are applied. The error carries structured migration data (orchestrationMigrationData('command_retired')) pointing the user to the orchestration skill and the required contract version.

Source

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

    }>('orchestration.dispatchShow', {
      task: getRequiredStringFlag(flags, 'task'),
      preamble: showPreamble,
      from,
      devMode: isDevCliInvocation()
    })
    printResult(result, json, (r) => {
      if (r.preamble && showPreamble) {
        return r.preamble
      }
      if (!r.dispatch) {
        return 'No dispatch context found.'
      }
      return `${r.dispatch.id} task=${r.dispatch.task_id} [${r.dispatch.status}]`
    })
  },

  'orchestration coordinator-start': async () => {
    throw new RuntimeClientError(
      'orchestration_migration_required',
      'The legacy automatic coordinator command is retired. No effects were applied.',
      orchestrationMigrationData('command_retired')
    )
  },

  'orchestration coordinator-stop': async () => {
    throw new RuntimeClientError(
      'orchestration_migration_required',
      'The legacy automatic coordinator command is retired. No effects were applied.',
      orchestrationMigrationData('command_retired')
    )
  },

  'orchestration gate-create': async ({ flags, client, cwd, json }) => {
    const result = await callMutation<{
      gate: { id: string; task_id: string; status: string }
    }>(client, flags, 'orchestration.gateCreate', {

View on GitHub (pinned to 1136503c6a)

Solutions

1. Stop using 'orchestration coordinator-start'; it is permanently retired.
2. Migrate to the Run model: use 'orchestration run-create' / 'run-use' and 'task-create' / 'dispatch' instead.
3. Run 'skills get orchestration --full' (the nextSteps in the error data) for the migration guide.

Example fix

// before
orca orchestration coordinator-start
// after
orca orchestration run-create --objective "coordinate feature X"

// The command is unconditionally retired; detect and reroute before calling.
const RETIRED = ['orchestration coordinator-start', 'orchestration coordinator-stop']
if (RETIRED.includes(command)) {
  // reroute to run-create / task-create / dispatch instead of invoking the CLI
}

function isRetiredCoordinatorCommand(cmd: string): boolean {
  return cmd === 'orchestration coordinator-start' || cmd === 'orchestration coordinator-stop'
}

try {
  await runCli('orchestration coordinator-start')
} catch (err) {
  if (err instanceof RuntimeClientError && err.code === 'orchestration_migration_required') {
    // migrate the caller to run-create/task-create/dispatch; do not retry the retired command
  } else { throw err }
}

When it happens

Trigger: Calling 'orchestration coordinator-start' under any circumstances — the handler body is a single throw with no conditions. It is reached whenever the CLI routes to this verb.

Common situations: Old scripts, docs, or muscle memory invoking the retired coordinator command after an Orca upgrade; automation that has not migrated to the Run-based model.

Related errors

• invalid_argument
• no_active_sender_terminal
• ${result.result.lifecycle.code}
• peek_wait_unsupported
• incompatible_runtime

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