paperclipai/paperclip · error · Error

Target worktree database appears to be running (pid ${runnin

Error message

Target worktree database appears to be running (pid ${runningTargetPid}). Stop Paperclip in ${target.rootPath} before repairing, or re-run with --allow-live-target if you want to override this guard.

What it means

Thrown in the cold-init branch of worktreeRepairCommand (the path taken when the target has no worktree-local config/env yet) when readRunningPostmasterPid finds a postmaster.pid in the target's embedded-postgres data dir whose pid is alive (process.kill(pid,0) succeeds) and --allow-live-target is not set. This protects against repairing/overwriting a DB that is actively running. A stale pid file (dead process) does NOT trip this guard because readRunningPostmasterPid returns null in that case.

Source

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

      fromConfig: source.configPath,
      to: target.rootPath,
      seedMode,
      preserveLiveWork: opts.preserveLiveWork,
      yes: true,
      allowLiveTarget: opts.allowLiveTarget,
    });
    return;
  }

  const repairInstanceId = sanitizeWorktreeInstanceId(path.basename(target.rootPath));
  const repairPaths = resolveWorktreeLocalPaths({
    cwd: target.rootPath,
    homeDir: resolveWorktreeHome(opts.home),
    instanceId: repairInstanceId,
  });
  const runningTargetPid = readRunningPostmasterPid(path.resolve(repairPaths.embeddedPostgresDataDir, "postmaster.pid"));
  if (runningTargetPid && !opts.allowLiveTarget) {
    throw new Error(
      `Target worktree database appears to be running (pid ${runningTargetPid}). Stop Paperclip in ${target.rootPath} before repairing, or re-run with --allow-live-target if you want to override this guard.`,
    );
  }
  if (runningTargetPid && opts.allowLiveTarget) {
    p.log.warning(`Proceeding even though the target embedded PostgreSQL appears to be running (pid ${runningTargetPid}).`);
  }

  const originalCwd = process.cwd();
  try {
    process.chdir(target.rootPath);
    await runWorktreeInit({
      home: opts.home,
      fromConfig: source.configPath,
      fromDataDir: opts.fromDataDir,
      fromInstance: opts.fromInstance,
      seed: opts.noSeed ? false : true,
      seedMode,
      preserveLiveWork: opts.preserveLiveWork,

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Stop the embedded PostgreSQL / Paperclip server holding that pid (e.g. stop `paperclipai dev` in the target worktree), then retry.
2. Re-run with --allow-live-target to override the guard if you are sure overwriting is safe.
3. Confirm the pid is genuinely Paperclip's embedded PG with `ps -p <pid> -o command=` before killing anything.

Example fix

// before
paperclipai worktree repair --branch feature-x
// after (stop the live target DB first)
# stop paperclipai dev / server in the target worktree, then
paperclipai worktree repair --branch feature-x
// or override
paperclipai worktree repair --branch feature-x --allow-live-target

import fs from "node:fs";
import path from "node:path";

function readLivePostmasterPid(dataDir: string): number | null {
  const pidFile = path.resolve(dataDir, "postmaster.pid");
  if (!fs.existsSync(pidFile)) return null;
  const pid = Number(fs.readFileSync(pidFile, "utf8").split("\n")[0]?.trim());
  if (!Number.isInteger(pid) || pid <= 0) return null;
  try { process.kill(pid, 0); return pid; } catch { return null; }
}

// before repair (cold branch), compute repairPaths.embeddedPostgresDataDir and check:
const livePid = readLivePostmasterPid(repairPaths.embeddedPostgresDataDir);
if (livePid && !opts.allowLiveTarget) {
  throw new Error(`Stop embedded PostgreSQL (pid ${livePid}) in the target worktree before repair, or pass --allow-live-target.`);
}

When it happens

Trigger: Calling `paperclipai worktree repair --branch <name>` where the target worktree's embedded PostgreSQL data dir contains a postmaster.pid whose process is still alive, without --allow-live-target.

Common situations: A previous `paperclipai worktree init`/`dev` left embedded PostgreSQL running in the target worktree. Or a crashed Paperclip process left embedded PostgreSQL orphaned but still running. The repair command wants to (re)initialize that data dir, so it refuses to clobber a live DB.

Related errors

• Target worktree database appears to be running (pid ${runnin
• Source and target Paperclip configs are the same. Use --from
• Unsupported seed mode "${seedMode}". Expected one of: minima
• Worktree config already exists at ${paths.configPath} or ins
• Cannot seed worktree database because source config was not

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