paperclipai/paperclip · error · Error

${extractExecSyncErrorMessage(error) ?? String(error)}

Error message

${extractExecSyncErrorMessage(error) ?? String(error)}

What it means

Thrown when `git worktree add` (via resolveGitWorktreeAddArgs) fails during worktree creation. The message is git's own stderr/stdout extracted by extractExecSyncErrorMessage, so it carries the precise reason git refused (e.g. branch already checked out elsewhere, invalid path, lock file held).

Source

Thrown at cli/src/commands/worktree.ts:1009

  }

  mkdirSync(path.dirname(targetPath), { recursive: true });

  const spinner = p.spinner();
  spinner.start(`Creating git worktree for ${branchName}...`);
  try {
    execFileSync("git", resolveGitWorktreeAddArgs({
      branchName,
      targetPath,
      branchExists: localBranchExists(repoRoot, branchName),
    }), {
      cwd: repoRoot,
      stdio: ["ignore", "pipe", "pipe"],
    });
    spinner.stop(`Created git worktree at ${targetPath}.`);
  } catch (error) {
    spinner.stop(pc.red("Failed to create git worktree."));
    throw new Error(extractExecSyncErrorMessage(error) ?? String(error));
  }

  installDependenciesBestEffort(targetPath);

  return {
    rootPath: targetPath,
    configPath: path.resolve(targetPath, ".paperclip", "config.json"),
    label: branchName,
    branchName,
    created: true,
  };
}

function resolveSourceConnectionString(config: PaperclipConfig, envEntries: Record<string, string>, portOverride?: number): string {
  if (config.database.mode === "postgres") {
    const connectionString = nonEmpty(envEntries.DATABASE_URL) ?? nonEmpty(config.database.connectionString);
    if (!connectionString) {
      throw new Error(

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Read the embedded git error text to identify the specific failure (most messages name the cause).
2. If the branch is checked out elsewhere, use a different branch or detach the other worktree first.
3. Run `git worktree prune` to clear stale worktree metadata and retry.
4. Remove any stale .git/*.lock files and ensure the target path is writable.

Example fix

# before
# (error from git worktree add)
# after
git worktree prune
git worktree list   # confirm no stale entry
paperclipai worktree ...

function branchIsNotCheckedOutElsewhere(repoRoot: string, branch: string): boolean {
  try {
    const list = execFileSync('git', ['worktree', 'list', '--porcelain'], { cwd: repoRoot, encoding: 'utf8' });
    return !list.split('\n').some(l => l.startsWith('branch ') && l.endsWith(branch));
  } catch { return true; }
}

try {
  await createWorktree(...);
} catch (e) {
  const msg = (e as Error).message;
  if (/already checked out|locked/i.test(msg)) { /* detach other worktree or pick new branch */ }
  else throw e;
}

When it happens

Trigger: Trying to create a worktree for a branch that is already checked out in another worktree; target path inside an existing worktree; a .git/worktrees lock is held; insufficient disk space or permissions; the branch name resolves to an existing but unrelated ref.

Common situations: Branch already checked out in the primary worktree; concurrent worktree operations; stale git lockfiles after a crash; branch name colliding with a tag or remote ref.

Related errors

• Target path already exists but is not a registered git workt
• Target path already exists: ${targetPath}
• Branch name is required.
• Invalid branch name "${branchName}": ${extractExecSyncErrorM
• Current directory is not inside a git repository.

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/14c514ec3771ef73. Report an issue: GitHub.