Warning: Worktree '${existingEnv.branch_name}' is not based

Error message

Warning: Worktree '${existingEnv.branch_name}' is not based on '${configuredBase}'. Recreate with: bun run cli complete ${existingEnv.branch_name} --force

What it means

Warning from the run precheck (packages/cli/src/commands/workflow.ts:2647), logged as 'worktree.reuse_base_branch_mismatch'. An existing worktree is being reused, but its branch was not cut from the currently configured base branch (e.g. the project's configured base changed, or the worktree is stale). Archon proceeds but warns, and tells you the exact command to recreate the environment.

Source

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

        if (flagBase) {
          configuredBase = git.toBranchName(flagBase);
        } else if (rawBase) {
          configuredBase = git.toBranchName(rawBase);
        } else if (codebaseDefaultBranch) {
          configuredBase = git.toBranchName(codebaseDefaultBranch);
        } else {
          configuredBase = await git.getDefaultBranch(git.toRepoPath(codebase.default_cwd));
        }
        const isValidBase = await git.isAncestorOf(
          git.toWorktreePath(existingEnv.working_path),
          `origin/${configuredBase}`
        );
        if (!isValidBase) {
          getLog().warn(
            { path: existingEnv.working_path, configuredBase, branch: existingEnv.branch_name },
            'worktree.reuse_base_branch_mismatch'
          );
          console.warn(
            `Warning: Worktree '${existingEnv.branch_name}' is not based on '${configuredBase}'. ` +
              `Recreate with: bun run cli complete ${existingEnv.branch_name} --force`
          );
        }
      } catch (e) {
        getLog().debug({ err: e }, 'worktree.reuse_base_branch_check_skipped');
        // Non-blocking — skip warning if base branch cannot be determined
      }
      getLog().info({ path: existingEnv.working_path }, 'worktree_reused');
      workingCwd = existingEnv.working_path;
      isolationEnvId = existingEnv.id;
    } else {
      // Create new worktree
      getLog().info(
        { branch: branchIdentifier, fromBranch: options.fromBranch },
        'worktree_creating'
      );

View on GitHub (pinned to 0773b97458)

Solutions

Recreate the worktree as the warning instructs: `bun run cli complete <branch> --force`, then re-run the workflow.
Or update your configuration so `configuredBase` matches what the worktree was actually cut from.
If the mismatch is intentional (long-lived worktree), acknowledge and continue — the run is not blocked.
Inspect the branch ancestry (`git merge-base`) to confirm the relationship before ignoring.

Example fix

// before: worktree cut from main, config now says develop
archon workflow run fix   # Warning: not based on 'develop'
// after
bun run cli complete feat/fix --force
archon workflow run fix

Defensive patterns

Strategy: validation

Validate before calling

// Verify the worktree base before reusing it
const base = execSync(`git -C ${worktree} merge-base HEAD ${configuredBase}`).toString().trim();
const head = execSync(`git -C ${worktree} rev-parse HEAD`).toString().trim();
const valid = base === head || isAncestor(base, head); // mirror the CLI's validity check

Prevention

Recreate worktrees after changing the configured base branch.
Avoid history rewrites on the base branch, or expect to recreate environments.
Periodically prune stale worktrees with `archon isolation complete <branch> --force`.

When it happens

Trigger: Reusing an existing worktree whose merge-base with `configuredBase` fails the validity check (`isValidBase` false) — typically after changing the configured base branch or after the base was rebased/reset.

Common situations: Team switched default branch from `main` to `develop` while old worktrees exist; base branch history rewritten; worktree created long ago from an ancestor commit no longer considered a valid base.

Related errors

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