paperclipai/paperclip · error

Embedded PostgreSQL support requires dependency `embedded-po

Error message

Embedded PostgreSQL support requires dependency `embedded-postgres`. Reinstall dependencies and try again.

What it means

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.

Source

Thrown at cli/src/commands/routines.ts:116

  if (!fs.existsSync(postmasterPidFile)) return null;
  try {
    const pid = Number(fs.readFileSync(postmasterPidFile, "utf8").split("\n")[0]?.trim());
    if (!Number.isInteger(pid) || pid <= 0) return null;
    process.kill(pid, 0);
    return pid;
  } catch {
    return null;
  }
}

async function ensureEmbeddedPostgres(dataDir: string, preferredPort: number): Promise<EmbeddedPostgresHandle> {
  const moduleName = "embedded-postgres";
  let EmbeddedPostgres: EmbeddedPostgresCtor;
  try {
    const mod = await import(moduleName);
    EmbeddedPostgres = mod.default as EmbeddedPostgresCtor;
  } catch {
    throw new Error(
      "Embedded PostgreSQL support requires dependency `embedded-postgres`. Reinstall dependencies and try again.",
    );
  }
  await prepareEmbeddedPostgresNativeRuntime();

  const postmasterPidFile = path.resolve(dataDir, "postmaster.pid");
  const runningPid = readRunningPostmasterPid(postmasterPidFile);
  if (runningPid) {
    return {
      port: readPidFilePort(postmasterPidFile) ?? preferredPort,
      startedByThisProcess: false,
      stop: async () => {},
    };
  }

  const port = await findAvailablePort(preferredPort);
  const logBuffer = createEmbeddedPostgresLogBuffer();
  const instance = new EmbeddedPostgres({

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Reinstall dependencies for the CLI workspace: `pnpm install` (ensure optional deps are not pruned).
2. Verify the package resolves: `node -e "import('embedded-postgres')"` from the cli directory.
3. If you did not intend embedded mode, change `database.mode` in your config to `postgres` and provide a `connectionString`.
4. On Node version change, rebuild native modules: `pnpm rebuild` or `pnpm install --force`.

Example fix

// before (config)
{ "database": { "mode": "embedded-postgres" } }
# after (reinstall)
pnpm install
# or switch mode
{ "database": { "mode": "postgres", "connectionString": "postgres://..." } }

import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
function embeddedPostgresAvailable(): boolean {
  try { require.resolve('embedded-postgres'); return true; } catch { return false; }
}
if (config.database.mode === 'embedded-postgres' && !embeddedPostgresAvailable()) {
  throw new Error('Install embedded-postgres before using embedded mode.');
}

try {
  await import('embedded-postgres');
} catch {
  console.error('Run `pnpm install` (do not prune optional deps) and retry.');
  process.exit(1);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to parse JSON at ${filePath}: ${err instanceof Error
• Company ID is required. Pass --company-id, set PAPERCLIP_COM
• Source path or URL is required.
• Invalid --collision value. Use: rename, skip, replace
• Invalid --target value. Use: new | existing

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/95d9f4a992f99d72. Report an issue: GitHub.