paperclipai/paperclip · error · Error

Cannot seed target embedded PostgreSQL at

Error message

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.

What it means

ensureEmbeddedPostgres() (cli/src/commands/worktree.ts:1142) prepares a target worktree's embedded PostgreSQL for seeding. It reads postmaster.pid in the data dir; if a live postmaster PID is found and options.allowExisting === false, it refuses to seed because another process (typically the worktree's own running service) owns that database. Seeding needs exclusive control of the cluster so the snapshot/clone is deterministic. The PID and data dir are printed for diagnosis.

Solutions

1. Stop the worktree service that owns the database (the process holding the PID named in the error), then re-run the seed
2. If no service is visibly running, verify the PID with `ps -p <pid>`; a live PID means some postmaster still holds the cluster
3. As a last resort, shut that PostgreSQL instance down cleanly (its postmaster PID responds to a normal stop) so the seed can start its own

Example fix

# before: target worktree service still running
$ paperclipai worktree ensure-seeded
Error: Cannot seed target embedded PostgreSQL at .../pgdata while it is already running (pid=12345)

# after
$ ps -p 12345          # identify the owning service
$ <stop that worktree service>
$ paperclipai worktree ensure-seeded

import { existsSync, readFileSync } from 'node:fs';
import path from 'node:path';

const pidFile = path.resolve(dataDir, 'postmaster.pid');
function postmasterAlive(): boolean {
  if (!existsSync(pidFile)) return false;
  const pid = Number.parseInt(readFileSync(pidFile, 'utf8').split('\n')[0] ?? '', 10);
  if (!Number.isInteger(pid)) return false;
  try { process.kill(pid, 0); return true; } catch { return false; }
}
if (postmasterAlive()) await stopOwningWorktreeService(); // before seeding

Catch the 'already running (pid=' message, surface the owning PID, stop that service, and re-run the seed once (bounded retry).

When it happens

Trigger: Running worktree ensure-seeded / reseed / repair while the target worktree's service is still up and its embedded PostgreSQL is running; any seed call that passes allowExisting: false against a data dir whose postmaster.pid names a live process.

Common situations: Forgetting to stop the worktree service before reseeding; a second terminal still running the service for that worktree; a leftover postmaster from a crashed service keeping the PID alive.

Related errors

• Failed to create a pending worktree seed manifest.
• Worktree seed source diagnostics changed while waiting for…
• ExternalChatWaitAuthorizationContentionError
• Failed to start worktree port reservation lock heartbeat at
• Invalid worktree seed manifest at

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

Appendix: source

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

  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 () => {},
    };
  }

  const port = await findAvailablePort(preferredPort);
  const logBuffer = createEmbeddedPostgresLogBuffer();
  const instance = new EmbeddedPostgres({
    databaseDir: dataDir,
    user: "paperclip",
    password: "paperclip",
    port,

View on GitHub (pinned to 01ad858492)