coleam00/Archon · error · Error

--stubs-init cannot be combined with --stubs.

Error message

--stubs-init cannot be combined with --stubs.

What it means

`--stubs-init` (generate an initial stub file) and `--stubs` (use an existing stub file) are alternative stub modes for a dry-run and cannot both be supplied. The check sits inside the --dry-run validation block.

Source

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

  }

  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
    );

    // Relative stub paths resolve from `--cwd`, as the CLI reference states. They are the
    // operator's dry-run inputs, not part of the workflow's source, so `--workflow-source`
    // must not silently move where they are read from or written to.

View on GitHub (pinned to 0773b97458)

Solutions

1. Keep --stubs to reuse an existing stub file, dropping --stubs-init
2. Or keep --stubs-init to generate fresh stubs, dropping --stubs

Example fix

// before
archon workflow run wf --dry-run --stubs-init stubs.yaml --stubs stubs.yaml
// after
archon workflow run wf --dry-run --stubs stubs.yaml

if (args.includes('--stubs-init') && args.includes('--stubs')) {
  throw new Error('--stubs-init and --stubs are mutually exclusive');
}

try {
  await runWorkflow(args);
} catch (e) {
  if (/--stubs-init cannot be combined/.test(String(e.message))) {
    return runWorkflow(args.filter(a => a !== '--stubs-init'));
  }
  throw e;
}

When it happens

Trigger: `archon workflow run wf --dry-run --stubs-init path --stubs other.yaml`; both options.stubsInitPath and options.stubsPath defined.

Common situations: Building on a script that seeds stubs with --stubs-init and later switching to a checked-in stubs file via --stubs without removing the other flag.

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

• --stubs-init cannot be combined with --default-stubs.
• --resume and --model are mutually exclusive. A resumed run k
• --dry-run cannot be combined with ${incompatibleFlag}.
• --branch and --no-worktree are mutually exclusive. --branc
• --from/--from-branch has no effect with --no-worktree. Remov

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