paperclipai/paperclip · error · Error

Cannot seed target embedded PostgreSQL at ${dataDir} while i

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.

Source

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

  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 a7e689b3c3)

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
Defensive patterns

Strategy: retry

Validate before calling

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

Try / catch

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

Prevention

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

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