{"record":{"id":"b657384aef3582f5","repo":"paperclipai/paperclip","slug":"registered-label-paperclip-config-is-missing-it","errorCode":null,"errorMessage":"Registered ${label} Paperclip config is missing its adjacent .env instance pointer.","messagePattern":"Registered (.+?) Paperclip config is missing its adjacent \\.env instance pointer\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/shared/src/worktree-seed-source.ts","lineNumber":34,"sourceCode":"};\n\nexport type RegisteredWorktreeSeedSourceInput = {\n  registeredBaseWorkspaceCwd?: string | null;\n  explicitSourceConfigPath?: string | null;\n  targetConfigPath: string;\n  expectedTargetInstanceId: string;\n};\n\nfunction readInstanceId(configPath: string, label: \"source\" | \"target\"): string {\n  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.","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/paperclipai/paperclip/blob/a7e689b3c35347b529cb9f54c9b9a8575a3dcab6/packages/shared/src/worktree-seed-source.ts#L16-L52","documentation":"Thrown by readInstanceId in worktree-seed-source.ts while resolving the registered source/target Paperclip config: the config's directory has no adjacent .env file, and the layout is not an instance-root config (whose parent directory is named \"instances\" and which identifies the instance by its own directory name). Worktree configs always ship an .env instance pointer, so its absence means a malformed or partially copied config.","triggerScenarios":"resolveRegisteredWorktreeSeedSource reads the source or target config.json, looks for .env in the same directory, does not find it, and path.basename(dirname(configDir)) !== \"instances\" — e.g. a worktree whose .env was never generated, or a config.json copied to a new location without its .env.","commonSituations":"Copying just config.json into a new checkout or dotfiles sync that skips .env files; a partially created worktree (interrupted setup); moving a workspace directory and losing the adjacent .env; git operations that clean ignored files (.env is typically ignored) after the config was committed.","solutions":["Create the missing .env next to config.json with a PAPERCLIP_INSTANCE_ID=<id> line (use the instance id of the Paperclip instance this config belongs to).","Prefer the instance-root layout <home>/instances/<id>/config.json, which needs no .env (the directory names the instance).","If the worktree setup was interrupted, re-run the worktree creation flow so it regenerates .env.","Check your sync/clean tooling (.gitignore rules, workspace cleaners) is not deleting the adjacent .env."],"exampleFix":"# before: <worktree>/.paperclip/config.json exists, no <worktree>/.paperclip/.env\n\n# after: create <worktree>/.paperclip/.env\nPAPERCLIP_INSTANCE_ID=inst_01J8ZQ...","handlingStrategy":"validation","validationCode":"import { existsSync } from \"node:fs\";\nimport path from \"node:path\";\nfunction configHasInstancePointer(configPath: string): boolean {\n  const dir = path.dirname(configPath);\n  return existsSync(path.join(dir, \".env\")) ||\n    path.basename(path.dirname(dir)) === \"instances\";\n}","typeGuard":null,"tryCatchPattern":"try {\n  resolveRegisteredWorktreeSeedSource(input);\n} catch (error) {\n  if (error instanceof Error && error.message.includes(\"missing its adjacent .env instance pointer\")) {\n    // create <configDir>/.env with PAPERCLIP_INSTANCE_ID=<id>, then retry\n  }\n  throw error;\n}","preventionTips":["Treat config.json and its .env as an inseparable pair when copying or backing up worktrees.","Prefer the instance-root layout (<home>/instances/<id>/config.json) which needs no .env.","Exclude .env from aggressive cleanup tooling in worktree directories."],"tags":["worktree","seed-source","config","env-file","filesystem"],"backgroundTag":"missing-config-file","analyzedSha":"a7e689b3c35347b529cb9f54c9b9a8575a3dcab6","analyzedAt":"2026-08-21T17:58:32.592Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}