paperclipai/paperclip · error

Configured worktree path "${worktreePath}" already exists an

Error message

Configured worktree path "${worktreePath}" already exists and is not a reusable git worktree${reason}.

What it means

Workspace preparation found the configured worktree path already exists on disk but validateReusableWorktree deemed it not a reusable git worktree (reason appended). Rather than clobber an unknown directory, preparation refuses and the operator must inspect or remove it.

Source

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

      }).catch(() => null);
      return {
        validation: nextValidation,
        branchName: effectiveBranchName,
        warnings: coherence.warnings,
      };
    }
    return { validation, branchName, warnings: [] };
  }

  const existingWorktree = await directoryExists(worktreePath);
  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,

View on GitHub (pinned to a7e689b3c3)

Solutions

1. Remove or relocate the existing directory at the worktree path, or fix it into a valid git worktree, then retry.

When it happens

Trigger: Thrown at server/src/services/workspace-runtime.ts:3187 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/502c7da1825177f3. Report an issue: GitHub.