paperclipai/paperclip · error

Configured worktree path

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.

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.

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