coleam00/Archon · error · Error

--branch and --no-worktree are mutually exclusive. --branc

Error message

--branch and --no-worktree are mutually exclusive.
  --branch creates an isolated worktree (safe).
  --no-worktree runs directly in your repo (no isolation).
Use one or the other.

What it means

Authoritative programmatic guard (cli.ts also checks for UX): `--branch` creates an isolated git worktree while `--no-worktree` runs directly in the repo; the two isolation choices contradict, so the invocation is rejected at workflowRunCommand.

Source

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

      // Same filter `checkFixture` applies: a stub an `all_done` join tolerated
      // never blocked anything, so naming it as a cause of this failure points
      // the reader at the wrong node (#2869).
      const blockingMissingStubs = result.missingStubs.filter(
        nodeId => !result.toleratedMissingStubs.includes(nodeId)
      );
      throw new Error(
        blockingMissingStubs.length > 0
          ? `Dry-run failed; missing stubs: ${blockingMissingStubs.join(', ')}`
          : 'Dry-run failed. See the trace for details.'
      );
    }
    return;
  }

  // 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) {

View on GitHub (pinned to 0773b97458)

Solutions

  1. Keep --branch (isolated worktree, safe) and remove --no-worktree
  2. Or keep --no-worktree and remove --branch

Example fix

// before
archon workflow run wf --branch feature/x --no-worktree
// after
archon workflow run wf --branch feature/x
Defensive patterns

Strategy: validation

Validate before calling

if (args.includes('--branch') && args.includes('--no-worktree')) {
  throw new Error('--branch and --no-worktree are mutually exclusive');
}

Try / catch

try {
  await runWorkflow(args);
} catch (e) {
  if (/--branch and --no-worktree/.test(String(e.message))) {
    return runWorkflow(args.filter(a => a !== '--no-worktree'));
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling `archon workflow run wf --branch x --no-worktree` or workflowRunCommand with both options.branchName and options.noWorktree set.

Common situations: A wrapper that always passes --branch combined with a config/script that sets --no-worktree for speed.

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