--resume and --config are mutually exclusive. A resumed run

Error message

--resume and --config are mutually exclusive. A resumed run keeps its original run config.

What it means

The Archon CLI main() rejects invoking a run with both --resume and --config (an internal detached run-config handoff). A resumed run must keep its original persisted run configuration, so supplying a replacement config is a contract violation. The CLI fails fast with the shared RESUME_RUN_CONFIG_CONFLICT message before touching the database.

Source

Thrown at packages/cli/src/cli.ts:438

  const requiresGitRepo = !noGitCommands.includes(command ?? '');
  let detachedRunConfig: WorkflowRunConfigInput | undefined;

  try {
    const detachedRunConfigPayload = values['internal-detached-run-config'];
    if (
      command === 'workflow' &&
      subcommand === 'run' &&
      typeof detachedRunConfigPayload === 'string'
    ) {
      const { decodeWorkflowRunConfigHandoff } =
        await import('@archon/core/config/run-config-handoff');
      detachedRunConfig = decodeWorkflowRunConfigHandoff(detachedRunConfigPayload);
      // Fail-fast for the decode step, not a second copy of the invariant: `workflow.ts`
      // still owns this rejection for every caller. A legitimately spawned detached child
      // cannot reach it — the parent refuses to seal a config for a continuation before it
      // forks — so this only fires on a hand-built `--internal-detached-run-config`, and
      // saves it a database round-trip on the way to the same message.
      if (resumeFlag) throw new Error(RESUME_RUN_CONFIG_CONFLICT);
    }

    const configOutsideRun = rejectConfigOutsideRun(command, subcommand, values.config);
    if (configOutsideRun) {
      console.error(configOutsideRun);
      return 1;
    }
    // `archon continue` was removed (#2846). Intercepted before the git gate so
    // stale invocations get the replacement pointer in any directory.
    if (command === 'continue') {
      return await fail(
        jsonFlag,
        "Removed: 'archon continue' inferred a run from a branch name.\n" +
          'Use: archon workflow run <name> --adopt <run-id> <input>\n' +
          'Find a prior run id with: archon workflow runs --open (or workflow get <run-id>)'
      );
    }
    // Note: orphaned run cleanup moved to `workflow cleanup` command only.

View on GitHub (pinned to 0773b97458)

Solutions

Remove the --config / --internal-detached-run-config flag from the resume command; the original run config is restored automatically.
If you need different settings, do not resume — start a new run with the desired config.
If a wrapper script constructs the command, fix it to omit config flags when resumeFlag is set.
To change future behavior of a resumed workflow, edit the workflow file and start a new run rather than re-sealing a config.

Example fix

// before
archon run --resume run_123 --config ./other.yaml
// after
archon run --resume run_123

Defensive patterns

Strategy: validation

Validate before calling

// Guard wrapper scripts from combining resume with a config flag
if (args.includes('--resume') && (args.includes('--config') || args.includes('--internal-detached-run-config'))) {
  throw new Error('Drop --config when resuming; the original run config is reused');
}

Prevention

Never hand-craft --internal-detached-run-config commands; let the parent spawn them.
Audit shell aliases/wrappers that unconditionally append --config.
Treat resume as config-immutable; start a new run for different settings.

When it happens

Trigger: Running a command with both `--resume <runId>` and `--internal-detached-run-config <payload>` (or the config flag it maps to), e.g. hand-crafting a detached continuation command or a wrapper script that adds --config to a resume invocation.

Common situations: Hand-built detached-child commands where the operator added a config flag; shell aliases that always append --config; scripted resumption of an interrupted run that mistakenly passes a new run config.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/273bf3f7edc59de0. Report an issue: GitHub.