coleam00/Archon · error · Error

--dry-run cannot be combined with ${incompatibleFlag}.

Error message

--dry-run cannot be combined with ${incompatibleFlag}.

What it means

`--dry-run` simulates a run and cannot be combined with flags that affect a real execution: --branch, --from/--from-branch, --container, --resume, or --detach. The CLI enumerates these pairs and throws naming the first offending flag.

Source

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

  const optionWithoutDryRun = dryRunOnlyOptions.find(([, present]) => present)?.[0];
  if (!options.dryRun && optionWithoutDryRun) {
    throw new Error(`${optionWithoutDryRun} requires --dry-run.`);
  }

  if (options.dryRun) {
    const incompatible = [
      ['--branch', options.branchName !== undefined],
      ['--from/--from-branch', options.fromBranch !== undefined],
      ['--base', options.baseBranch !== undefined],
      ['--no-worktree', options.noWorktree === true],
      ['--folder', options.folder === true],
      ['--container', options.container === true],
      ['--resume', options.resume === true],
      ['--detach', options.detach === true],
    ] as const;
    const incompatibleFlag = incompatible.find(([, present]) => present)?.[0];
    if (incompatibleFlag) {
      throw new Error(`--dry-run cannot be combined with ${incompatibleFlag}.`);
    }
    if (options.stubsInitPath !== undefined && options.stubsPath !== undefined) {
      throw new Error('--stubs-init cannot be combined with --stubs.');
    }
    if (options.stubsInitPath !== undefined && options.defaultStubs) {
      throw new Error('--stubs-init cannot be combined with --default-stubs.');
    }

    // The IDENTICAL invocation gate a real run passes through below (#2610): parse
    // `--input name=value`, validate against the declared `inputs:` contract, and fail
    // with the same errors (undeclared key, missing required) before any trace output.
    // Only the supplied entries travel; the simulator derives declared defaults itself,
    // mirroring the executor's `defaultRunInputs` merge at run start.
    const dryRunInputs = resolveTopLevelInputs(
      workflow,
      options.inputs ? parseInputAssignments(options.inputs) : undefined
    );

View on GitHub (pinned to 0773b97458)

Solutions

  1. Remove the incompatible flag named in the message
  2. Or drop --dry-run if you actually want a real run with that flag

Example fix

// before
archon workflow run wf --dry-run --detach
// after
archon workflow run wf --dry-run
Defensive patterns

Strategy: validation

Validate before calling

if (args.includes('--dry-run')) {
  const bad = ['--branch','--from','--from-branch','--container','--resume','--detach']
    .find(f => args.includes(f));
  if (bad) throw new Error(`--dry-run cannot be combined with ${bad}`);
}

Try / catch

try {
  await runWorkflow(args);
} catch (e) {
  if (/--dry-run cannot be combined/.test(String(e.message))) {
    const flag = String(e.message).split('combined with ')[1];
    return runWorkflow(args.filter(a => a !== flag));
  }
  throw e;
}

Prevention

When it happens

Trigger: e.g. `archon workflow run wf --dry-run --detach`, or --dry-run together with --resume/--container/--branch.

Common situations: Combining a simulation with worktree/branch isolation flags out of habit; scripts that always pass --resume but are pointed at a dry-run test.

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