{"record":{"id":"439610f314ada827","repo":"paperclipai/paperclip","slug":"registered-label-paperclip-config-has-no-paperc","errorCode":null,"errorMessage":"Registered ${label} Paperclip config has no PAPERCLIP_INSTANCE_ID binding.","messagePattern":"Registered (.+?) Paperclip config has no PAPERCLIP_INSTANCE_ID binding\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/shared/src/worktree-seed-source.ts","lineNumber":44,"sourceCode":"  const configDir = path.dirname(configPath);\n  const envPath = path.join(configDir, \".env\");\n  if (!existsSync(envPath)) {\n    // An instance-root config (`<home>/instances/<id>/config.json`) names its instance\n    // by directory rather than by an adjacent .env; worktree configs always ship one.\n    if (path.basename(path.dirname(configDir)) === \"instances\") {\n      return resolvePaperclipInstanceId(path.basename(configDir));\n    }\n    throw new Error(`Registered ${label} Paperclip config is missing its adjacent .env instance pointer.`);\n  }\n  const contents = readFileSync(envPath, \"utf8\");\n  for (const rawLine of contents.split(/\\r?\\n/)) {\n    const match = rawLine.match(\n      /^\\s*(?:export\\s+)?PAPERCLIP_INSTANCE_ID\\s*=\\s*(?:\"([^\"]*)\"|'([^']*)'|([^\\s#]+))/,\n    );\n    const value = (match?.[1] ?? match?.[2] ?? match?.[3] ?? \"\").trim();\n    if (value) return value;\n  }\n  throw new Error(`Registered ${label} Paperclip config has no PAPERCLIP_INSTANCE_ID binding.`);\n}\n\nfunction errorCode(error: unknown): string {\n  return (error as NodeJS.ErrnoException | null)?.code ?? \"unknown error\";\n}\n\n/**\n * Inspect a directory entry without following it, returning null only when it is absent.\n *\n * Any other failure means the declared path is unreadable or malformed, and a guess there\n * would silently seed from a different instance.\n */\nfunction inspectDeclaredEntry(entryPath: string, configPath: string, detail?: string): Stats | null {\n  try {\n    return lstatSync(entryPath);\n  } catch (error) {\n    if (errorCode(error) === \"ENOENT\") return null;\n    throw new Error(","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/paperclipai/paperclip/blob/a7e689b3c35347b529cb9f54c9b9a8575a3dcab6/packages/shared/src/worktree-seed-source.ts#L26-L62","documentation":"Thrown by readInstanceId in worktree-seed-source.ts when the .env adjacent to a registered Paperclip config exists but contains no parseable PAPERCLIP_INSTANCE_ID assignment. The parser accepts optional `export`, double/single quotes, and unquoted values, but a file with only other variables (or only commented-out lines) yields no identity, and the resolver refuses to guess which instance the config belongs to.","triggerScenarios":"resolveRegisteredWorktreeSeedSource finds <configDir>/.env, reads it line by line, and no line matches PAPERCLIP_INSTANCE_ID=... — e.g. an .env holding only PAPERCLIP_API_URL, or PAPERCLIP_INSTANCE_ID commented out with '#'.","commonSituations":"Template .env files shipped with placeholders commented out; hand-edited .env where the variable was renamed (INSTANCE_ID, PAPERCLIP_ID); whitespace/typo variants the regex does not cover (missing '=', typo in the name); multiple config copies sharing a generic .env.","solutions":["Add a line PAPERCLIP_INSTANCE_ID=<your-instance-id> to the .env next to config.json.","Uncomment the existing line if it is commented, and fix the exact spelling PAPERCLIP_INSTANCE_ID.","Verify with a quick grep: grep -n 'PAPERCLIP_INSTANCE_ID' <configDir>/.env must print exactly one assignment.","If you do not know the instance id, read it from the instance-root directory name (<home>/instances/<id>) or the Paperclip server config."],"exampleFix":"# before (.paperclip/.env)\n# PAPERCLIP_INSTANCE_ID=inst_old\nPAPERCLIP_API_URL=http://localhost:3100\n\n# after\nPAPERCLIP_INSTANCE_ID=inst_01J8ZQ...\nPAPERCLIP_API_URL=http://localhost:3100","handlingStrategy":"validation","validationCode":"import { readFileSync, existsSync } from \"node:fs\";\nimport path from \"node:path\";\nfunction envBindsInstanceId(configPath: string): boolean {\n  const envPath = path.join(path.dirname(configPath), \".env\");\n  if (!existsSync(envPath)) return false;\n  return /^\\s*(?:export\\s+)?PAPERCLIP_INSTANCE_ID\\s*=/m.test(readFileSync(envPath, \"utf8\"));\n}","typeGuard":null,"tryCatchPattern":"try {\n  resolveRegisteredWorktreeSeedSource(input);\n} catch (error) {\n  if (error instanceof Error && error.message.includes(\"no PAPERCLIP_INSTANCE_ID binding\")) {\n    // append PAPERCLIP_INSTANCE_ID=<id> to <configDir>/.env, then retry\n  }\n  throw error;\n}","preventionTips":["Template .env files with the variable active, not commented out.","Use the exact name PAPERCLIP_INSTANCE_ID (quotes and export are allowed).","Validate worktree configs with a small lint (grep for the binding) in CI."],"tags":["worktree","seed-source","config","env-file","instance-id"],"backgroundTag":"missing-env-var","analyzedSha":"a7e689b3c35347b529cb9f54c9b9a8575a3dcab6","analyzedAt":"2026-08-21T17:58:32.592Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}