Cannot delete branch '${options.branchName}': worktree path

Error message

Cannot delete branch '${options.branchName}': worktree path gone and no canonicalRepoPath provided

What it means

Not a thrown error but a warning string recorded in destroy()'s result.warnings in packages/isolation/src/providers/worktree.ts. When the worktree path is already gone and no canonicalRepoPath was supplied, destroy cannot run 'git worktree remove' or resolve the repo, so a stale branch named via options.branchName cannot be pruned; the warning documents the skipped branch cleanup.

Source

Thrown at packages/isolation/src/providers/worktree.ts:257

    if (!pathExists) {
      getLog().debug({ worktreePath }, 'worktree_path_already_removed');
      result.worktreeRemoved = true; // Already gone counts as removed
      result.directoryClean = true;
    }

    // Get canonical repo path - use provided path or derive from worktree
    let repoPath: string;
    if (options?.canonicalRepoPath) {
      repoPath = (await getGitCommandAnchors(options.canonicalRepoPath)).durable;
    } else if (pathExists) {
      repoPath = (await getGitCommandAnchors(worktreePath)).durable;
    } else {
      // Path doesn't exist and no canonicalRepoPath provided - can't clean up branch
      // This is expected when worktree was already fully cleaned up externally
      if (options?.branchName) {
        const warning = `Cannot delete branch '${options.branchName}': worktree path gone and no canonicalRepoPath provided`;
        getLog().warn({ worktreePath, branchName: options.branchName }, 'branch_cleanup_skipped');
        result.warnings.push(warning);
      }
      return result;
    }

    // Only attempt worktree removal if path exists
    if (pathExists) {
      const gitArgs = ['-C', repoPath, 'worktree', 'remove'];
      if (options?.force) {
        gitArgs.push('--force');
      }
      gitArgs.push(worktreePath);

      try {
        await execFileAsync('git', gitArgs, { timeout: GIT_OPERATION_TIMEOUT_MS });
        result.worktreeRemoved = true;
      } catch (error) {
        if (!this.isWorktreeMissingError(error)) {
          throw error;

View on GitHub (pinned to 0773b97458)

Solutions

Pass canonicalRepoPath in the destroy options so the provider can delete the branch even when the worktree path is gone
Delete the branch manually: git -C <canonicalRepoPath> branch -D <branchName> (or git worktree prune first)
Treat the warning as benign if the worktree was already fully cleaned up externally, as the code notes
Make teardown idempotent: run git worktree prune and branch deletion as separate best-effort steps

Example fix

// before
await provider.destroy({ worktreePath, branchName: 'archon/issue-42' });
// after
await provider.destroy({
  worktreePath,
  branchName: 'archon/issue-42',
  canonicalRepoPath: '/repos/main-checkout',
});

Defensive patterns

Strategy: fallback

Validate before calling

const pathExists = existsSync(worktreePath);
const repoExists = options.canonicalRepoPath ? existsSync(options.canonicalRepoPath) : false;
if (!pathExists && options.branchName && !repoExists) {
  console.warn(`Branch ${options.branchName} may be orphaned; no repo available to delete it`);
}

Type guard

function hasBranchCleanupWarning(result: DestroyResult): boolean {
  return result.warnings.some(w => w.startsWith("Cannot delete branch '"));
}

Try / catch

const result = await provider.destroy({ worktreePath, branchName, canonicalRepoPath });
for (const w of result.warnings) {
  if (w.includes('Cannot delete branch')) {
    getLog().warn({ worktreePath, w }, 'branch cleanup skipped; pruning manually');
    await exec('git -C ' + canonicalRepoPath + ' worktree prune');
    await exec('git -C ' + canonicalRepoPath + ' branch -D ' + branchName);
  }
}

Prevention

Always pass canonicalRepoPath when destroying a worktree whose branch you want gone
Treat destroy() as idempotent and inspect result.warnings, not just thrown errors
Run git worktree prune after external/manual worktree deletion
Make teardown a single tracked step so branch cleanup is not lost

When it happens

Trigger: Calling destroy({ branchName }) on a worktree whose directory no longer exists on disk, without providing canonicalRepoPath in options.

Common situations: A previous cleanup pass already deleted the worktree directory but not its branch; manual rm -rf of the worktree; calling destroy twice; CI re-running teardown after an earlier successful destroy.

Related errors

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