paperclipai/paperclip · error

Registered worktree for branch "${branchName}" at "${registe

Error message

Registered worktree for branch "${branchName}" at "${registeredBranchWorktree}" is not reusable${reason}.

What it means

Git already has a worktree registered for the target branch at a different path, and that registered worktree is not reusable (reason appended). The branch cannot be checked out into a new worktree while the stale registration exists.

Source

Thrown at server/src/services/workspace-runtime.ts:3257

  if (existingWorktree) {
    const reusable = await validateReusableWorktree(worktreePath);
    if (reusable.validation?.valid) {
      return await reuseExistingWorktree(worktreePath, reusable.branchName, reusable.warnings);
    }
    const validation = reusable.validation;
    const reason = validation && !validation.valid ? ` (${validation.reason})` : "";
    throw new Error(`Configured worktree path "${worktreePath}" already exists and is not a reusable git worktree${reason}.`);
  }

  const registeredBranchWorktree = await findRegisteredGitWorktreeByBranch(repoRoot, branchName);
  if (registeredBranchWorktree) {
    const reusable = await validateReusableWorktree(registeredBranchWorktree);
    if (reusable.validation?.valid) {
      return await reuseExistingWorktree(registeredBranchWorktree, reusable.branchName, reusable.warnings);
    }
    const validation = reusable.validation;
    const reason = validation && !validation.valid ? ` (${validation.reason})` : "";
    throw new Error(`Registered worktree for branch "${branchName}" at "${registeredBranchWorktree}" is not reusable${reason}.`);
  }

  try {
    await recordGitOperation(input.recorder, {
      phase: "worktree_prepare",
      args: ["worktree", "add", "-b", branchName, worktreePath, baseRef],
      cwd: repoRoot,
      metadata: {
        repoRoot,
        worktreePath,
        branchName,
        baseRef,
        baseRefSha: currentBaseRefSha,
        created: true,
      },
      successMessage: `Created git worktree at ${worktreePath}\n`,
      failureLabel: `git worktree add ${worktreePath}`,
    });

View on GitHub (pinned to a7e689b3c3)

Solutions

1. The registered worktree for the branch is not reusable. Prune/repair it ('git worktree prune' or remove and recreate) and retry.

When it happens

Trigger: Thrown at server/src/services/workspace-runtime.ts:3198 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@a7e689b3c3 (2026-08-18). Data as JSON: /api/errors/1fc2b472f8053ad6. Report an issue: GitHub.