coleam00/Archon · error · Error

--base has no effect with --no-worktree. Remove --base or dr

Error message

--base has no effect with --no-worktree.
Remove --base or drop --no-worktree.

What it means

The Archon CLI's workflow-start preflight in packages/cli/src/commands/workflow.ts rejects flag combinations that cannot be honored. `--base` (baseBranch) only controls which branch a new git worktree is cut from; when `--no-worktree` is passed the run executes in the live checkout, so `--base` would be silently ignored. The CLI fails loudly instead of dropping the flag.

Source

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

  // Validate mutually exclusive flags (defensive — cli.ts checks these for UX, but
  // workflowRunCommand is the authoritative boundary for programmatic callers)
  if (options.branchName !== undefined && options.noWorktree) {
    throw new Error(
      '--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.'
    );
  }

View on GitHub (pinned to 0773b97458)

Solutions

Remove the `--base <branch>` flag from the command.
Remove `--no-worktree` if you actually need the run to start from a specific base branch.
If you need a specific starting point in the live checkout, check out the desired branch yourself before launching the run.

Example fix

// before
archon workflow start code-review --no-worktree --base main
// after
archon workflow start code-review --no-worktree

Defensive patterns

Strategy: validation

Validate before calling

if (args.includes('--no-worktree') && args.includes('--base')) {
  throw new Error('--base has no effect with --no-worktree; drop one of them.');
}

Prevention

Keep worktree-related flags (--base, --branch, --from, --no-worktree) in mutually exclusive script branches.
Template CI invocations without --base when they use --no-worktree.

When it happens

Trigger: Running `archon workflow start <name> --no-worktree --base <branch>` (or setting options.baseBranch programmatically alongside options.noWorktree in the workflow-start options object).

Common situations: Scripts templated from a worktree-based invocation being switched to `--no-worktree` for CI or quick local runs while keeping `--base`; users assuming `--base` influences the live-checkout run's behavior.

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/2ab1001ca8f0264d. Report an issue: GitHub.