coleam00/Archon · error

Failed to create worktree for PR #

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.

Solutions

1. Read the inner message after 'Failed to create worktree for PR #N:' — it names the failing git step
2. Run `git worktree prune` and delete stale `pr-N-review` branches, then retry
3. Re-fetch the PR (`git fetch origin pull/N/head` or the PR branch) to confirm it still exists and is reachable
4. For fork PRs, ensure the fork's commits are fetched/available locally before creation
5. 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

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 {
  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;
}

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

• merge check failed
• Warning
• Cannot adopt worktree at
• Cannot adopt : .git pointer is not a git-worktree reference.
• Cannot delete branch

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

Appendix: 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)