Failed to create worktree for PR #${prNumber}: ${err.message

Error message

Failed to create worktree for PR #${prNumber}: ${err.message}

What it means

createFromPR wraps all PR worktree creation (same-repo branch checkout or fork synthetic branch). If any step fails partway — e.g. `git worktree add` succeeded but creating the local tracking branch failed — the orphaned worktree is cleaned up and the original error is rewrapped with the PR number for context.

Source

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

    await this.cleanOrphanDirectoryIfExists(worktreePath);

    const repoPath = request.canonicalRepoPath;
    const prNumber = request.identifier;

    try {
      if (!request.isForkPR) {
        // Same-repo PR: Use the actual branch so changes push directly to PR
        await this.createFromSameRepoPR(repoPath, worktreePath, request.prBranch, remote);
      } else {
        // Fork PR: Use synthetic review branch
        await this.createFromForkPR(repoPath, worktreePath, prNumber, remote, request.prSha);
      }
    } catch (error) {
      // Clean up orphaned git-registered worktree from partial failure
      // (e.g., worktree add succeeded but createBranchWithStaleRetry failed)
      await this.cleanOrphanWorktreeIfExists(repoPath, worktreePath);
      const err = error as Error;
      throw new Error(`Failed to create worktree for PR #${prNumber}: ${err.message}`);
    }
  }

  /**
   * Create worktree for same-repo PR using the actual branch
   */
  private async createFromSameRepoPR(
    repoPath: string,
    worktreePath: string,
    prBranch: string,
    remote = 'origin'
  ): Promise<void> {
    // Fetch the PR's actual branch
    await execFileAsync('git', ['-C', repoPath, 'fetch', remote, prBranch], {
      timeout: GIT_OPERATION_TIMEOUT_MS,
    });

    // Try to create worktree with the branch

View on GitHub (pinned to 0773b97458)

Solutions

Read the inner message after 'Failed to create worktree for PR #N:' — it names the failing git step
Run `git worktree prune` and delete stale `pr-N-review` branches, then retry
Re-fetch the PR (`git fetch origin pull/N/head` or the PR branch) to confirm it still exists and is reachable
For fork PRs, ensure the fork's commits are fetched/available locally before creation
Check disk space and that the target worktree path is not locked by another process

Example fix

# before
git branch -a | grep pr-42-review  # stale branch blocks creation
# after
git branch -D pr-42-review && git worktree prune  # then rerun

Defensive patterns

Strategy: try-catch

Validate before calling

import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
const execFileAsync = promisify(execFile);
export async function assertPrStateReady(repoPath: string, prBranch: string): Promise<void> {
  await execFileAsync('git', ['-C', repoPath, 'worktree', 'prune']);
  await execFileAsync('git', ['-C', repoPath, 'fetch', 'origin', prBranch]); // throws if branch is gone/unreachable
}

Try / catch

try {
  const env = await provider.create(prRequest);
} catch (e) {
  const msg = (e as Error).message;
  if (msg.startsWith('Failed to create worktree for PR #')) {
    console.error('Prune stale worktrees/branches and confirm the PR branch is fetchable, then retry:', msg);
  }
  throw e;
}

Prevention

Run `git worktree prune` regularly to remove stale registrations
Delete stale `pr-N-review` branches after reviews complete
Confirm PR branches are still open and fetchable before creating review worktrees
For fork PRs, fetch the fork ref/SHA before creation

When it happens

Trigger: WorktreeProvider handling a PRIsolationRequest where the underlying git operations fail: fetch of the PR branch fails, `git worktree add` fails (path exists, branch collision), or createBranchWithStaleRetry cannot create the tracking branch (stale branch name, ref conflict).

Common situations: PR branch deleted or force-pushed between listing and checkout; leftover worktree/branch from a previous failed run with the same pr-N name; fork PR whose SHA is unreachable because the fork remote was never fetched; network failure mid-creation.

Related errors

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