Worktree branch '${env.branch_name}' is not based on '${base

Error message

Worktree branch '${env.branch_name}' is not based on '${baseBranch}'. Recreate with: archon complete ${env.branch_name} --force

What it means

resolver.collectBaseBranchWarnings checks whether an existing environment's worktree branch is actually based on the workflow's expected base branch. If the merge-base check shows it is not, the environment is reused only with this warning telling the operator the branch lineage diverges from the requested base and how to force a recreation.

Source

Thrown at packages/isolation/src/resolver.ts:253

   * Returns a warning string if mismatched, empty array otherwise.
   * Never throws — validation errors are non-blocking.
   */
  private async collectBaseBranchWarnings(
    env: IsolationEnvironmentRow,
    baseBranch: BranchName | undefined,
    logContext: Record<string, unknown>
  ): Promise<string[]> {
    if (!baseBranch) return [];
    try {
      const isValid = await isAncestorOf(toWorktreePath(env.working_path), `origin/${baseBranch}`);
      if (!isValid) {
        getLog().warn(
          { ...logContext, branchName: env.branch_name, baseBranch },
          'isolation.reuse_base_branch_mismatch'
        );
        return [
          `Worktree branch '${env.branch_name}' is not based on '${baseBranch}'. ` +
            `Recreate with: archon complete ${env.branch_name} --force`,
        ];
      }
    } catch (err) {
      getLog().warn(
        { err, ...logContext, branchName: env.branch_name, baseBranch },
        'isolation.reuse_base_branch_check_failed'
      );
    }
    return [];
  }

  /**
   * Check if an existing environment reference is still valid.
   */
  private async checkExisting(
    envId: string,
    baseBranch?: BranchName
  ): Promise<IsolationResolution | null> {

View on GitHub (pinned to 0773b97458)

Solutions

Recreate the environment as the message says: `archon complete <branch> --force`.
Verify the intended base with `git merge-base <branch> <baseBranch>` and rebase the branch onto it.
Update the workflow's base-branch configuration if the expectation, not the branch, is wrong.

Example fix

// before
archon complete fix-auth   # reuses env, warns base mismatch
// after
archon complete fix-auth --force   # recreates branch from current base

Defensive patterns

Strategy: validation

Validate before calling

const base = await git(['merge-base', branchName, baseBranch], repoPath);
const tip = await git(['rev-parse', baseBranch], repoPath);
const isBased = (await git(['rev-parse', `${base}^{commit}`], repoPath)) !== '' ;
// lineage check: ensure branch fork point is an ancestor of current base tip
const ok = await git(['merge-base', '--is-ancestor', base.trim(), tip.trim()]);

Try / catch

const warnings = resolver.warnings(env);
if (warnings.some(w => w.includes('is not based on'))) {
  // recreate: archon complete <branch> --force
}

Prevention

Recreate environments after changing the workflow base branch.
Run `archon complete <branch> --force` when in doubt about lineage.
Keep environment branches short-lived and derived from the current base.

When it happens

Trigger: Reusing an environment whose branch_name was created from a different base than baseBranch (e.g. repo default changed, or the branch predates a workflow-base switch).

Common situations: Changing the workflow's base branch config while old environments exist; long-lived branches created before a rebase or default-branch rename; running `archon complete <branch>` normally instead of --force.

Related errors

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