{"record":{"id":"e64a299c6968d015","repo":"paperclipai/paperclip","slug":"worktree-seed-source-is-not-registered-managed-bo","errorCode":null,"errorMessage":"Worktree seed source is not registered. Managed boot requires a project workspace; manual boot requires --from-config.","messagePattern":"Worktree seed source is not registered\\. Managed boot requires a project workspace; manual boot requires --from-config\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/shared/src/worktree-seed-source.ts","lineNumber":121,"sourceCode":"    throw new Error(`${label} does not exist at ${resolved}.`);\n  }\n  if (canonical !== resolved || lstatSync(resolved).isSymbolicLink()) {\n    throw new Error(`${label} must be a canonical path and cannot use a symlink alias.`);\n  }\n  if (!lstatSync(canonical).isFile()) {\n    throw new Error(`${label} is not a regular file at ${canonical}.`);\n  }\n  return canonical;\n}\n\n/** Resolve the authoritative source and target identities without consulting diagnostics. */\nexport function resolveRegisteredWorktreeSeedSource(\n  input: RegisteredWorktreeSeedSourceInput,\n): CanonicalWorktreeSeedSource {\n  const registeredCwd = input.registeredBaseWorkspaceCwd?.trim();\n  const explicitSource = input.explicitSourceConfigPath?.trim();\n  if (!registeredCwd && !explicitSource) {\n    throw new Error(\n      \"Worktree seed source is not registered. Managed boot requires a project workspace; manual boot requires --from-config.\",\n    );\n  }\n\n  let canonicalBaseCwd: string | null = null;\n  let registeredConfigPath: string | null = null;\n  if (registeredCwd) {\n    const resolvedRegisteredCwd = path.resolve(registeredCwd);\n    try {\n      canonicalBaseCwd = realpathSync(resolvedRegisteredCwd);\n    } catch {\n      throw new Error(`Registered base project workspace does not exist at ${resolvedRegisteredCwd}.`);\n    }\n    if (canonicalBaseCwd !== resolvedRegisteredCwd) {\n      throw new Error(\"Registered base project workspace must be canonical and cannot use a symlink alias.\");\n    }\n    if (!lstatSync(canonicalBaseCwd).isDirectory()) {\n      throw new Error(`Registered base project workspace is not a directory at ${canonicalBaseCwd}.`);","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/paperclipai/paperclip/blob/a7e689b3c35347b529cb9f54c9b9a8575a3dcab6/packages/shared/src/worktree-seed-source.ts#L103-L139","documentation":"resolveRegisteredWorktreeSeedSource() needs to know which Paperclip instance to seed from, and it got neither a registered base workspace cwd nor an explicit --from-config path. Managed boot derives the source from a registered project workspace; manual boot requires an explicit config, and with both absent there is nothing authoritative to resolve.","triggerScenarios":"Calling worktree-seed resolution with `registeredBaseWorkspaceCwd` null/blank and `explicitSourceConfigPath` null/blank; running the seed command in a scratch directory that is not a registered project workspace and without --from-config.","commonSituations":"Running `paperclip worktree ...` from a fresh clone or /tmp with no prior `paperclip register/init`; CI jobs starting in a clean checkout; whitespace-only registration values after a config edit; scripts that conditionally pass --from-config and skip it in one branch.","solutions":["Run the command from inside a registered project workspace (one known to the Paperclip instance), or re-register it.","Pass an explicit source: add `--from-config <path-to-config.json>` pointing at a valid instance config.","If you expected a registration to exist, check the instance's registered workspaces list to see whether the cwd matches."],"exampleFix":"# before\npaperclip worktree seed   # run from /tmp, no registration, no flag\n\n# after\npaperclip worktree seed --from-config ~/.paperclip/instances/<instance-id>/config.json","handlingStrategy":"validation","validationCode":"const hasSeedSource = Boolean(\n  (input.registeredBaseWorkspaceCwd ?? \"\").trim() ||\n  (input.explicitSourceConfigPath ?? \"\").trim(),\n);\nif (!hasSeedSource) {\n  throw new Error(\"pass --from-config or run inside a registered workspace\");\n}","typeGuard":"type SeedInput =\n  | { registeredBaseWorkspaceCwd: string; explicitSourceConfigPath?: string }\n  | { registeredBaseWorkspaceCwd?: null; explicitSourceConfigPath: string };\n\nconst hasRequiredSeedSource = (i: RegisteredWorktreeSeedSourceInput): i is SeedInput =>\n  Boolean(i.registeredBaseWorkspaceCwd?.trim() ?? i.explicitSourceConfigPath?.trim());","tryCatchPattern":null,"preventionTips":["Make --from-config required in scripts that may run outside registered workspaces.","Fail fast in CLI wrappers with a clear usage message when neither source is present.","Document that managed boot requires running from the registered checkout root."],"tags":["cli","worktree-seed","missing-argument","config"],"backgroundTag":"missing-required-option","analyzedSha":"a7e689b3c35347b529cb9f54c9b9a8575a3dcab6","analyzedAt":"2026-08-21T17:58:32.592Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}