{"record":{"id":"cc504e1c78523383","repo":"EveryInc/compound-engineering-plugin","slug":"context-collectionpath-exists-and-is-not-a-syml","errorCode":null,"errorMessage":"${context.collectionPath} exists and is not a symlink; refusing to overwrite it","messagePattern":"(.+?) exists and is not a symlink; refusing to overwrite it","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/dev/codex-dev.ts","lineNumber":266,"sourceCode":"    } catch {\n      return { kind: \"unrelated\", target, resolvedTarget }\n    }\n    if (path.basename(resolvedTarget) !== \"skills\") {\n      return { kind: \"unrelated\", target, resolvedTarget }\n    }\n    return { kind: \"valid\", target, resolvedTarget }\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") return { kind: \"broken\", target }\n    throw error\n  }\n}\n\nexport async function activateLocalCollection(context: CodexDevContext): Promise<void> {\n  await fs.mkdir(path.dirname(context.collectionPath), { recursive: true })\n  const desiredTarget = await fs.realpath(context.skillsRoot)\n  const state = await inspectLocalCollection(context)\n  if (state.kind === \"collision\") {\n    throw new Error(`${context.collectionPath} exists and is not a symlink; refusing to overwrite it`)\n  }\n  if (state.kind === \"unrelated\") {\n    throw new Error(`${context.collectionPath} points outside a Compound Engineering checkout; refusing to overwrite it`)\n  }\n  if (state.kind === \"broken\") {\n    throw new Error(`${context.collectionPath} is a broken symlink; refusing to overwrite it`)\n  }\n  if (state.kind === \"valid\" && state.resolvedTarget === desiredTarget) return\n\n  await replaceManagedCollectionLink(context.collectionPath, desiredTarget, state)\n}\n\nexport type ManagedCollectionLinkExpectation =\n  | { kind: \"absent\" }\n  | { kind: \"valid\"; target: string }\n\nexport async function removeManagedCollectionLink(\n  collectionPath: string,","sourceCodeStart":248,"sourceCodeEnd":284,"githubUrl":"https://github.com/EveryInc/compound-engineering-plugin/blob/c9c10f8c75412c7232cb2bd663e5fd1cea98d84e/src/dev/codex-dev.ts#L248-L284","documentation":"activateLocalCollection creates $CODEX_HOME/skills/compound-engineering-local as a symlink to the checkout's skills directory. Before linking it inspects the existing path; if something non-symlink already occupies that location (a real directory or file) it is reported as a \"collision\" and the library refuses to overwrite, protecting user data at ~/.codex/skills.","triggerScenarios":"Calling activateLocalCollection (via codex:dev -- local/refresh) when <codexHome>/skills/compound-engineering-local already exists as a real directory or regular file — inspectLocalCollection returns kind \"collision\" (src/dev/codex-dev.ts:266).","commonSituations":"A previous manual install copied skills into that directory; an older plugin version installed a real directory there; a backup/restore recreated the path as a plain folder.","solutions":["Inspect what is there: ls -la ~/.codex/skills/compound-engineering-local.","If the contents are unwanted or duplicates of the plugin skills, remove them: rm -rf ~/.codex/skills/compound-engineering-local, then re-run the local command.","If the contents matter, move them aside: mv ~/.codex/skills/compound-engineering-local ~/.codex/skills/compound-engineering-local.bak, then re-run.","Prefer bun run codex:dev -- remove first — it sweeps known stale install surfaces before re-linking."],"exampleFix":"// before\n~/.codex/skills/compound-engineering-local/   // real directory\ncodex:dev -- local  // error: exists and is not a symlink\n// after\nmv ~/.codex/skills/compound-engineering-local{,.bak}\ncodex:dev -- local  // symlink created","handlingStrategy":"try-catch","validationCode":"import { lstat } from \"node:fs/promises\"\nimport path from \"node:path\"\nconst p = path.join(process.env.CODEX_HOME || path.join(process.env.HOME!, \".codex\"), \"skills\", \"compound-engineering-local\")\ntry {\n  const s = await lstat(p)\n  if (!s.isSymbolicLink()) console.warn(`${p} is a real ${s.isDirectory() ? \"directory\" : \"file\"}; move it aside before linking`)\n} catch { /* absent: safe to link */ }","typeGuard":null,"tryCatchPattern":"try {\n  await activateLocalCollection(ctx)\n} catch (error) {\n  if ((error as Error).message.includes(\"exists and is not a symlink\")) {\n    console.error(`Move aside or remove ${ctx.collectionPath}, then retry`)\n  } else throw error\n}","preventionTips":["Never manually copy skill folders into ~/.codex/skills/compound-engineering-local.","Run bun run codex:dev -- remove before switching install strategies.","Check ls -la ~/.codex/skills/compound-engineering-local when upgrading from older installs."],"tags":["filesystem","symlink","safety"],"backgroundTag":"path-collision-refuses-overwrite","analyzedSha":"c9c10f8c75412c7232cb2bd663e5fd1cea98d84e","analyzedAt":"2026-08-31T15:18:07.959Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}