coleam00/Archon · error · Error

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

Error message

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

What it means

`--stubs-init` cannot be combined with `--default-stubs` (use built-in default stubs): both decide where dry-run stub values come from, so supplying both is ambiguous. Same validation block as the --stubs conflict.

Source

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

    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.
    const stubsPath = options.stubsPath
      ? isAbsolute(options.stubsPath)
        ? options.stubsPath

View on GitHub (pinned to 0773b97458)

Solutions

  1. Drop --stubs-init if the built-in defaults suffice
  2. Or drop --default-stubs if you want a generated stub file at --stubs-init's path

Example fix

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

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

When it happens

Trigger: `archon workflow run wf --dry-run --stubs-init path --default-stubs`; options.stubsInitPath defined while options.defaultStubs is true.

Common situations: A wrapper that adds --default-stubs for convenience colliding with a script that also passes --stubs-init to materialize stubs.

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