paperclipai/paperclip · error · 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') fails. The worktree reseed needs embedded-postgres to run a local postgres instance for the dump/restore; without the native dependency it cannot proceed.

Source

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

    );
  }

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

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. Run `pnpm install` (or the repo's install command) to ensure embedded-postgres is installed.
2. Confirm the package resolves from the cli workspace: `pnpm why embedded-postgres` / `ls node_modules/embedded-postgres`.
3. Verify your platform/arch has supported native binaries; if not, run on a supported platform or use external postgres mode.
4. Ensure prepareEmbeddedPostgresNativeRuntime's prerequisites (toolchain/libc) are present.

Example fix

# before: missing dep
# after
pnpm install && pnpm --filter @paperclipai/cli rebuild

async function embeddedPostgresAvailable(): Promise<boolean> {
  try { await import('embedded-postgres'); return true; } catch { return false; }
}

try {
  await ensureEmbeddedPostgres(dataDir, port);
} catch (e) {
  if (/embedded-postgres/.test((e as Error).message)) {
    console.error('Run `pnpm install` to install embedded-postgres, or use external postgres mode.');
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: embedded-postgres not installed in the CLI package's node_modules; install was partial/failed; the package is an optionalDependency that was skipped on this platform; native runtime (prepareEmbeddedPostgresNativeRuntime) prerequisites missing so the import throws.

Common situations: Fresh checkout without pnpm install; partial install on a platform where embedded-postgres native binaries were skipped; monorepo hoisting left embedded-postgres inaccessible to the cli package; Node version incompatibility breaking the native addon.

Related errors

• --version is only supported for npm package installs, not lo
• Approval request failed.
• Invalid --secret-value "${raw}". Use key=value.
• ${error instanceof Error ? error.message : String(error)}\n$
• Circular workspace dependency while staging ${packageName}.

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