paperclipai/paperclip · error · Error

Embedded PostgreSQL support requires dependency…

Error message

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

What it means

The CLI worktree command could not import the optional embedded-postgres package; local embedded database support in the CLI requires that dependency to be installed, and the import failure is rethrown as this explicit error.

Solutions

1. Reinstall dependencies so `embedded-postgres` is present, then retry.

When it happens

Trigger: Thrown at cli/src/commands/worktree.ts:1094 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-21). Data as JSON: /api/errors/270bab93fd92a129. Report an issue: GitHub.

Appendix: source

Thrown at cli/src/commands/worktree.ts:1114

  try {
    chmodSync(input.targetKeyFilePath, 0o600);
  } catch {
    // best effort
  }
}

export async function ensureEmbeddedPostgres(
  dataDir: string,
  preferredPort: number,
  options: { allowExisting?: boolean } = {},
): Promise<EmbeddedPostgresHandle> {
  const moduleName = "embedded-postgres";
  let EmbeddedPostgres: EmbeddedPostgresCtor;
  try {
    const mod = await loadWithoutEmbeddedPostgresExitHooks(() => 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) {
    if (options.allowExisting === false) {
      throw new Error(
        `Cannot seed target embedded PostgreSQL at ${dataDir} while it is already running (pid=${runningPid}). `
        + "Stop the worktree service that owns this database, then retry the seed.",
      );
    }
    return {
      port: readPidFilePort(postmasterPidFile) ?? preferredPort,
      startedByThisProcess: false,
      stop: async () => {},

View on GitHub (pinned to 01ad858492)