{"record":{"id":"77cfd8afe88d1ac0","repo":"paperclipai/paperclip","slug":"worktree-config-already-exists-at-paths-configpa","errorCode":null,"errorMessage":"Worktree config already exists at ${paths.configPath} or instance data exists at ${paths.instanceRoot}. Re-run with --force to replace it.","messagePattern":"Worktree config already exists at (.+?) or instance data exists at (.+?)\\. Re-run with --force to replace it\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/worktree.ts","lineNumber":1643,"sourceCode":"  const seedMode = opts.seedMode ?? \"minimal\";\n  if (!isWorktreeSeedMode(seedMode)) {\n    throw new Error(`Unsupported seed mode \"${seedMode}\". Expected one of: minimal, full.`);\n  }\n  const instanceId = sanitizeWorktreeInstanceId(opts.instance ?? worktreeName);\n  const paths = resolveWorktreeLocalPaths({\n    cwd,\n    homeDir: resolveWorktreeHome(opts.home),\n    instanceId,\n  });\n  const branding = {\n    name: opts.name ?? worktreeName,\n    color: opts.color ?? generateWorktreeColor(),\n  };\n  const sourceConfigPath = resolveSourceConfigPath(opts);\n  const sourceConfig = existsSync(sourceConfigPath) ? readConfig(sourceConfigPath) : null;\n\n  if ((existsSync(paths.configPath) || existsSync(paths.instanceRoot)) && !opts.force) {\n    throw new Error(\n      `Worktree config already exists at ${paths.configPath} or instance data exists at ${paths.instanceRoot}. Re-run with --force to replace it.`,\n    );\n  }\n\n  if (opts.force) {\n    // Only remove the specific files we're about to rewrite, not the whole\n    // repoConfigDir — that directory can contain sibling state such as\n    // <repo>/.paperclip/worktrees/ holding every repo-managed worktree\n    // checkout, and a recursive rmSync here would nuke them all.\n    rmSync(paths.configPath, { force: true });\n    rmSync(paths.envPath, { force: true });\n    const seedMarkers = resolveWorktreeSeedMarkerPaths(paths.configPath);\n    rmSync(seedMarkers.pending, { force: true });\n    rmSync(seedMarkers.complete, { force: true });\n    rmSync(paths.instanceRoot, { recursive: true, force: true });\n  }\n\n  const claimedPorts = collectClaimedWorktreePorts(paths.homeDir, paths.instanceId, paths.cwd);","sourceCodeStart":1625,"sourceCodeEnd":1661,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/worktree.ts#L1625-L1661","documentation":"Thrown by runWorktreeInit when EITHER the target config path OR the instance data root already exists and --force was not supplied. This protects against clobbering an existing worktree instance (its config.json, env file, and the isolated home dir under ~/.paperclip/instances/<id>). The check fires before any write so existing state is preserved.","triggerScenarios":"Running `worktree:init` twice with the same instance id/name; an earlier init crashed mid-way leaving config.json or the instance dir behind; re-running after a partial failure without cleaning up; using the same --instance id across two worktrees.","commonSituations":"Developer iterates on worktree setup and forgets the previous init succeeded partially; CI re-runs a job on the same runner without cleanup; two terminals init the same instance name.","solutions":["If the existing instance is disposable, re-run with --force to replace the config, env, seed markers, and instance root.","If you want to keep it, use a different --instance <id> or --name.","Clean up first: `paperclipai worktree:clean <name>` then re-init.","Inspect the paths in the error message to decide which is the stale one before forcing."],"exampleFix":"// before\npaperclipai worktree:init --instance feat-a\n# error: config/instance already exists\n// after (intentional replacement)\npaperclipai worktree:init --instance feat-a --force","handlingStrategy":"validation","validationCode":"import { existsSync } from \"node:fs\";\n\nfunction requireCleanTarget(paths: { configPath: string; instanceRoot: string }, force: boolean): void {\n  if (force) return;\n  if (existsSync(paths.configPath) || existsSync(paths.instanceRoot)) {\n    throw new Error(`Worktree already exists; pass --force or clean first.`);\n  }\n}","typeGuard":"function worktreeTargetOccupied(paths: { configPath: string; instanceRoot: string }): boolean {\n  return existsSync(paths.configPath) || existsSync(paths.instanceRoot);\n}","tryCatchPattern":"try { await runWorktreeInit(opts); }\ncatch (err) {\n  if (/already exists/.test(String((err as Error).message))) {\n    opts.force = true; // or prompt user\n    await runWorktreeInit(opts);\n  } else throw err;\n}","preventionTips":["Check for existing config/instance dir before init.","Use unique --instance ids per worktree.","Run `worktree:clean <name>` before re-initializing the same name."],"tags":["worktree","validation","cli","filesystem"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}