coleam00/Archon · error · Error

--resume and --branch are mutually exclusive. --resume reu

Error message

--resume and --branch are mutually exclusive.
  --resume reuses the existing worktree from the failed run.
  Remove --branch when using --resume.

What it means

The workflow-start preflight rejects `--resume` together with `--branch`. Resuming reuses the worktree and branch from the original failed run, so a caller-supplied branch name has no lane to apply to and would be silently dropped. The CLI surfaces the conflict with an explicit remedy instead.

Source

Thrown at packages/cli/src/commands/workflow.ts:1840

      '--branch and --no-worktree are mutually exclusive.\n' +
        '  --branch creates an isolated worktree (safe).\n' +
        '  --no-worktree runs directly in your repo (no isolation).\n' +
        'Use one or the other.'
    );
  }
  if (options.noWorktree && options.fromBranch !== undefined) {
    throw new Error(
      '--from/--from-branch has no effect with --no-worktree.\n' +
        'Remove --from or drop --no-worktree.'
    );
  }
  if (options.noWorktree && options.baseBranch !== undefined) {
    throw new Error(
      '--base has no effect with --no-worktree.\n' + 'Remove --base or drop --no-worktree.'
    );
  }
  if (options.resume && options.branchName !== undefined) {
    throw new Error(
      '--resume and --branch are mutually exclusive.\n' +
        '  --resume reuses the existing worktree from the failed run.\n' +
        '  Remove --branch when using --resume.'
    );
  }
  if (options.resume && options.inputs !== undefined && options.inputs.length > 0) {
    throw new Error(
      '--resume and --input are mutually exclusive.\n' +
        "  A resume replays the original invocation's inputs, recorded on the run.\n" +
        '  Drop --input to resume, or start a fresh run to supply different values.'
    );
  }

  // Between-run continuation (#2747): adoption dictates the lane itself, so the
  // lane-choosing flags are refused rather than silently overridden.
  if (options.adoptRunId !== undefined) {
    const conflicts: string[] = [];
    if (options.resume) conflicts.push('--resume');

View on GitHub (pinned to 0773b97458)

Solutions

Drop `--branch` from the resume command; the original run's worktree and branch are reused automatically.
If you truly want a new branch, drop `--resume` and start a fresh run with `--branch <name>` instead.

Example fix

// before
archon workflow start code-review --resume --branch fix/thing
// after
archon workflow start code-review --resume

Defensive patterns

Strategy: validation

Validate before calling

if (args.includes('--resume') && args.includes('--branch')) {
  throw new Error('--branch is implied by --resume; remove --branch.');
}

Prevention

Use --resume bare; never append lane flags to a resume command.
If a shared launcher adds --branch, gate it on absence of --resume.

When it happens

Trigger: `archon workflow start <name> --resume --branch <name>` — any resume invocation where options.branchName is also set.

Common situations: Retrying a failed run via `--resume` while copy-pasting a `--branch` flag from the original fresh-run command line; scripts that always pass `--branch`.

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/5f3ea408c04728f9. Report an issue: GitHub.