coleam00/Archon · error · Error

Workflow '${workflow.name}' sets worktree.enabled: false (ru

Error message

Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).
  --base only applies when a worktree is created.
  Drop --base or change the workflow's worktree.enabled.

What it means

A workflow pinned to `worktree.enabled: false` never creates a worktree, so `--base` — the branch a new worktree would be cut from — would be silently ignored. The CLI throws instead, keeping the policy-vs-flag mismatch explicit.

Source

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

  // rather than silently applying one side and ignoring the other.
  const pinnedEnabled = workflow.worktree?.enabled;
  if (pinnedEnabled === false) {
    if (options.branchName !== undefined) {
      throw new Error(
        `Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).\n` +
          '  --branch requires an isolated worktree.\n' +
          "  Drop --branch or change the workflow's worktree.enabled."
      );
    }
    if (options.fromBranch !== undefined) {
      throw new Error(
        `Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).\n` +
          '  --from/--from-branch only applies when a worktree is created.\n' +
          "  Drop --from or change the workflow's worktree.enabled."
      );
    }
    if (options.baseBranch !== undefined) {
      throw new Error(
        `Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).\n` +
          '  --base only applies when a worktree is created.\n' +
          "  Drop --base or change the workflow's worktree.enabled."
      );
    }
    // --no-worktree is redundant but not contradictory — silently accept.
  } else if (pinnedEnabled === true) {
    if (options.noWorktree) {
      throw new Error(
        `Workflow '${workflow.name}' sets worktree.enabled: true (requires a worktree).\n` +
          '  --no-worktree conflicts with the workflow policy.\n' +
          "  Drop --no-worktree or change the workflow's worktree.enabled."
      );
    }
  }

  // Default to worktree isolation unless --no-worktree or --resume. Workflow YAML
  // `worktree.enabled` pins the decision — mismatches with CLI flags are rejected

View on GitHub (pinned to 0773b97458)

Solutions

Drop the `--base` flag when starting this workflow.
Set `worktree.enabled: true` in the workflow YAML if `--base` should apply.
Note `--no-worktree` in this mode is redundant but accepted — only contradictory worktree flags throw.

Example fix

// before
archon workflow start live-sync --base main
// after
archon workflow start live-sync

Defensive patterns

Strategy: validation

Validate before calling

if (wf.worktree?.enabled === false && args.includes('--base')) {
  throw new Error(`${wf.name} never creates a worktree; --base is not applicable.`);
}

Prevention

Don't blanket-add --base to every workflow launch.
When a workflow is pinned to the live checkout, only flags like --input and --resume are meaningful.

When it happens

Trigger: `archon workflow start <workflow-with-worktree-enabled-false> --base <branch>` — options.baseBranch set while workflow.worktree.enabled === false.

Common situations: Standard launch templates that always include `--base main`; confusion between the workflow's isolation policy and per-dispatch overrides.

Related errors

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