{"record":{"id":"95d9f4a992f99d72","repo":"paperclipai/paperclip","slug":"embedded-postgresql-support-requires-dependency-e","errorCode":null,"errorMessage":"Embedded PostgreSQL support requires dependency `embedded-postgres`. Reinstall dependencies and try again.","messagePattern":"Embedded PostgreSQL support requires dependency `embedded-postgres`\\. Reinstall dependencies and try again\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/src/commands/routines.ts","lineNumber":116,"sourceCode":"  if (!fs.existsSync(postmasterPidFile)) return null;\n  try {\n    const pid = Number(fs.readFileSync(postmasterPidFile, \"utf8\").split(\"\\n\")[0]?.trim());\n    if (!Number.isInteger(pid) || pid <= 0) return null;\n    process.kill(pid, 0);\n    return pid;\n  } catch {\n    return null;\n  }\n}\n\nasync function ensureEmbeddedPostgres(dataDir: string, preferredPort: number): Promise<EmbeddedPostgresHandle> {\n  const moduleName = \"embedded-postgres\";\n  let EmbeddedPostgres: EmbeddedPostgresCtor;\n  try {\n    const mod = await import(moduleName);\n    EmbeddedPostgres = mod.default as EmbeddedPostgresCtor;\n  } catch {\n    throw new Error(\n      \"Embedded PostgreSQL support requires dependency `embedded-postgres`. Reinstall dependencies and try again.\",\n    );\n  }\n  await prepareEmbeddedPostgresNativeRuntime();\n\n  const postmasterPidFile = path.resolve(dataDir, \"postmaster.pid\");\n  const runningPid = readRunningPostmasterPid(postmasterPidFile);\n  if (runningPid) {\n    return {\n      port: readPidFilePort(postmasterPidFile) ?? preferredPort,\n      startedByThisProcess: false,\n      stop: async () => {},\n    };\n  }\n\n  const port = await findAvailablePort(preferredPort);\n  const logBuffer = createEmbeddedPostgresLogBuffer();\n  const instance = new EmbeddedPostgres({","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/routines.ts#L98-L134","documentation":"Thrown by ensureEmbeddedPostgres() when the dynamic `import(\"embedded-postgres\")` rejects. The package is an optional native dependency used only when config database.mode is `embedded-postgres`, so a missing/corrupt install surfaces here rather than at startup.","triggerScenarios":"Config sets `database.mode = \"embedded-postgres\"` but the `embedded-postgres` npm package is not installed, was pruned by `--production`/`--omit=optional`, has a broken native binary, or node_modules is partially installed. Produced by ensureEmbeddedPostgres() at routines.ts:116, invoked from openConfiguredDb and disableAllRoutinesInConfig.","commonSituations":"Running the routines CLI against an embedded-postgres config after a fresh clone without installing optional deps; CI caches that strip optional packages; switching Node versions so the native postgres binary is ABI-incompatible.","solutions":["Reinstall dependencies for the CLI workspace: `pnpm install` (ensure optional deps are not pruned).","Verify the package resolves: `node -e \"import('embedded-postgres')\"` from the cli directory.","If you did not intend embedded mode, change `database.mode` in your config to `postgres` and provide a `connectionString`.","On Node version change, rebuild native modules: `pnpm rebuild` or `pnpm install --force`."],"exampleFix":"// before (config)\n{ \"database\": { \"mode\": \"embedded-postgres\" } }\n# after (reinstall)\npnpm install\n# or switch mode\n{ \"database\": { \"mode\": \"postgres\", \"connectionString\": \"postgres://...\" } }","handlingStrategy":"try-catch","validationCode":"import { createRequire } from 'node:module';\nconst require = createRequire(import.meta.url);\nfunction embeddedPostgresAvailable(): boolean {\n  try { require.resolve('embedded-postgres'); return true; } catch { return false; }\n}\nif (config.database.mode === 'embedded-postgres' && !embeddedPostgresAvailable()) {\n  throw new Error('Install embedded-postgres before using embedded mode.');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await import('embedded-postgres');\n} catch {\n  console.error('Run `pnpm install` (do not prune optional deps) and retry.');\n  process.exit(1);\n}","preventionTips":["Pin and install optional dependencies in CI; never use --production/--omit=optional for the CLI workspace when embedded mode is configured.","After switching Node versions, run pnpm rebuild to refresh native modules."],"tags":["dependencies","embedded-postgres","config","native-module","import"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}