{"record":{"id":"794337da629741b5","repo":"paperclipai/paperclip","slug":"label-is-not-a-regular-file-at-canonical","errorCode":null,"errorMessage":"${label} is not a regular file at ${canonical}.","messagePattern":"(.+?) is not a regular file at (.+?)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/shared/src/worktree-seed-source.ts","lineNumber":109,"sourceCode":"      );\n    }\n  }\n  return false;\n}\n\nfunction canonicalRegularFile(filePath: string, label: string): string {\n  const resolved = path.resolve(filePath);\n  let canonical: string;\n  try {\n    canonical = realpathSync(resolved);\n  } catch {\n    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;","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/paperclipai/paperclip/blob/a7e689b3c35347b529cb9f54c9b9a8575a3dcab6/packages/shared/src/worktree-seed-source.ts#L91-L127","documentation":"After resolving successfully, canonicalRegularFile() lstats the canonical path and finds it is not a regular file (a directory, FIFO, socket, or device). Config paths must be plain files because the loader reads them as JSON, so anything else is rejected before parsing.","triggerScenarios":"A config path pointing at a directory (e.g. passing `.../.paperclip` instead of `.../.paperclip/config.json`); a config path occupied by a named pipe or socket created by tooling; /dev or other special nodes given as --from-config.","commonSituations":"Truncated path in scripts or shell history (dropping the `config.json` segment); mount points or bind mounts placed over the config location; a directory created where a file was expected by a mis-written provisioning step.","solutions":["Verify with `ls -la <resolved>` and `file <resolved>` what actually sits at the path.","Point the call at the real config file (`<...>/.paperclip/config.json`), not its directory.","If a directory/FIFO was created by mistake, remove it and restore a regular config.json file."],"exampleFix":"# before\npaperclip worktree seed --from-config ~/.paperclip/instances/myid   # directory\n\n# after\npaperclip worktree seed --from-config ~/.paperclip/instances/myid/config.json","handlingStrategy":"validation","validationCode":"import { statSync } from \"node:fs\";\n\nfunction assertRegularConfigFile(p: string): void {\n  const st = statSync(p); // throws ENOENT if absent — handle first\n  if (!st.isFile()) throw new Error(`${p} is not a regular file`);\n}","typeGuard":"const isRegularFile = (p: string): boolean => {\n  try { return require(\"node:fs\").statSync(p).isFile(); } catch { return false; }\n};","tryCatchPattern":"try {\n  resolveRegisteredWorktreeSeedSource(input);\n} catch (e) {\n  if (e instanceof Error && /not a regular file/.test(e.message)) {\n    // path pointed at a directory/special node — fix the path, not retryable\n  } else throw e;\n}","preventionTips":["Always terminate config paths with the explicit `config.json` filename.","In provisioning scripts, assert `fs.statSync(p).isFile()` before registering or seeding.","Never let mount points or FIFOs occupy expected config locations."],"tags":["filesystem","config","worktree-seed","validation"],"backgroundTag":"not-a-regular-file","analyzedSha":"a7e689b3c35347b529cb9f54c9b9a8575a3dcab6","analyzedAt":"2026-08-21T17:58:32.592Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}