paperclipai/paperclip · error

Worktree config already exists at

Error message

Worktree config already exists at ${paths.configPath} or instance data exists at ${paths.instanceRoot}. Re-run with --force to replace it.

What it means

Idempotency guard in worktree init: a Paperclip config or instance data directory already exists at the computed paths, so initialization would clobber an existing instance unless the operator explicitly passes --force.

Solutions

1. Re-run with --force to replace the existing worktree config and instance data.
2. Remove ${paths.configPath} and ${paths.instanceRoot} manually, then retry.

When it happens

Trigger: Thrown at cli/src/commands/worktree.ts:1643 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/77cfd8afe88d1ac0. Report an issue: GitHub.

Appendix: source

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

  const seedMode = opts.seedMode ?? "minimal";
  if (!isWorktreeSeedMode(seedMode)) {
    throw new Error(`Unsupported seed mode "${seedMode}". Expected one of: minimal, full.`);
  }
  const instanceId = sanitizeWorktreeInstanceId(opts.instance ?? worktreeName);
  const paths = resolveWorktreeLocalPaths({
    cwd,
    homeDir: resolveWorktreeHome(opts.home),
    instanceId,
  });
  const branding = {
    name: opts.name ?? worktreeName,
    color: opts.color ?? generateWorktreeColor(),
  };
  const sourceConfigPath = resolveSourceConfigPath(opts);
  const sourceConfig = existsSync(sourceConfigPath) ? readConfig(sourceConfigPath) : null;

  if ((existsSync(paths.configPath) || existsSync(paths.instanceRoot)) && !opts.force) {
    throw new Error(
      `Worktree config already exists at ${paths.configPath} or instance data exists at ${paths.instanceRoot}. Re-run with --force to replace it.`,
    );
  }

  if (opts.force) {
    // Only remove the specific files we're about to rewrite, not the whole
    // repoConfigDir — that directory can contain sibling state such as
    // <repo>/.paperclip/worktrees/ holding every repo-managed worktree
    // checkout, and a recursive rmSync here would nuke them all.
    rmSync(paths.configPath, { force: true });
    rmSync(paths.envPath, { force: true });
    const seedMarkers = resolveWorktreeSeedMarkerPaths(paths.configPath);
    rmSync(seedMarkers.pending, { force: true });
    rmSync(seedMarkers.complete, { force: true });
    rmSync(paths.instanceRoot, { recursive: true, force: true });
  }

  const { serverPort, databasePort, targetConfig } = await withWorktreePortRegistryLock(

View on GitHub (pinned to 01ad858492)