coleam00/Archon · error · Error

${optionWithoutDryRun} requires --dry-run.

Error message

${optionWithoutDryRun} requires --dry-run.

What it means

Several flags (--stubs, --default-stubs, --exec-code, --pause-at-gates) only make sense in dry-run simulation mode. The CLI throws when any is supplied without `--dry-run`, preventing flags that would otherwise be silently ignored in a real run.

Source

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

  emitParseWarnings(workflowEntry?.parseWarnings, workflow.name);
  emitDeprecationNotice(workflow);

  if (isContinuation && options.modelAssignments && options.modelAssignments.length > 0) {
    throw new Error(
      '--resume and --model are mutually exclusive. A resumed run keeps its original model bindings.'
    );
  }

  const dryRunOnlyOptions = [
    ['--stubs', options.stubsPath !== undefined],
    ['--stubs-init', options.stubsInitPath !== undefined],
    ['--default-stubs', options.defaultStubs === true],
    ['--exec-code', options.execCode === true],
    ['--pause-at-gates', options.pauseAtGates === true],
  ] as const;
  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) {

View on GitHub (pinned to 0773b97458)

Solutions

  1. Add --dry-run to the invocation
  2. Or remove the dry-run-only flags if you actually intended a real run

Example fix

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

Strategy: validation

Validate before calling

const dryRunOnly = ['--stubs','--default-stubs','--exec-code','--pause-at-gates'];
if (!args.includes('--dry-run') && args.some(a => dryRunOnly.some(f => a.startsWith(f)))) {
  throw new Error('These flags require --dry-run: ' + dryRunOnly.join(', '));
}

Try / catch

try {
  await runWorkflow(args);
} catch (e) {
  if (/requires --dry-run\./.test(String(e.message))) {
    return runWorkflow(['--dry-run', ...args]);
  }
  throw e;
}

Prevention

When it happens

Trigger: `archon workflow run wf --stubs stubs.yaml` without `--dry-run`; same for --default-stubs, --exec-code, or --pause-at-gates passed alone.

Common situations: Testing a workflow with stubs but forgetting the --dry-run flag; a wrapper script passing stub options in real-run mode.

Related errors

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