Embedded PostgreSQL process ${pid} did not stop within ${POS

Error message

Embedded PostgreSQL process ${pid} did not stop within ${POSTGRES_STOP_TIMEOUT_MS}ms.

What it means

During worktree instance cleanup, the embedded PostgreSQL process (pid from postmaster.pid) was sent SIGINT but was still alive after the POSTGRES_STOP_TIMEOUT_MS grace period. Cleanup aborts rather than delete a data directory under a live postmaster.

Source

Thrown at server/src/services/workspace-instance-cleanup.ts:183

  const canonicalRecordedDataDir = await fs.realpath(recordedDataDir).catch(() => path.resolve(recordedDataDir));
  if (canonicalRecordedDataDir !== canonicalDataDir) {
    throw new Error(`Refusing to remove ${dataDir}: postmaster.pid points at a different PostgreSQL data directory.`);
  }
  if (!dependencies.processIsAlive(pid)) return false;
  if (await dependencies.readVerifiedPostgresCommand(pid, canonicalDataDir) === null) return false;

  try {
    dependencies.signalProcess(pid, "SIGINT");
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ESRCH") return false;
    throw error;
  }
  const deadline = Date.now() + POSTGRES_STOP_TIMEOUT_MS;
  while (Date.now() < deadline) {
    if (!dependencies.processIsAlive(pid)) return true;
    await dependencies.wait(100);
  }
  throw new Error(`Embedded PostgreSQL process ${pid} did not stop within ${POSTGRES_STOP_TIMEOUT_MS}ms.`);
}

export async function readWorktreeInstancePointer(workspacePath: string): Promise<WorktreeInstancePointer | null> {
  const envPath = path.join(workspacePath, ".paperclip", ".env");
  try {
    return {
      envPath,
      envContents: await fs.readFile(envPath, "utf8"),
    };
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
    throw error;
  }
}

function resolveConfiguredInstanceRoot(pointer: WorktreeInstancePointer, expectedInstanceId?: string):
  | { instanceRoot: string; instanceId: string }
  | { warning: string; instanceRoot: string | null; refusalReason: string | null } {

View on GitHub (pinned to a7e689b3c3)

Solutions

The embedded PostgreSQL process ignored SIGTERM. Investigate why it is stuck (hung connections) and consider force-killing the PID, then retry cleanup.

Defensive patterns

Strategy: retry

When it happens

Trigger: Thrown at server/src/services/workspace-instance-cleanup.ts:161 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

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