{"record":{"id":"afa6edcd821b29b7","repo":"paperclipai/paperclip","slug":"the-running-embedded-postgresql-identity-does-not-match-this","errorCode":null,"errorMessage":"The running embedded PostgreSQL identity does not match this instance. Startup stopped before connecting.","messagePattern":"The running embedded PostgreSQL identity does not match this instance\\. Startup stopped before connecting\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/src/embedded-postgres-owner.ts","lineNumber":10,"sourceCode":"import { resolve } from \"node:path\";\n\n/** postmaster.pid records the actual listening port, which can differ from the\n * configured port after collision avoidance. Never reuse the configured port. */\nexport function embeddedPostgresOwnerPort(contents: string, dataDir: string, expectedPid: number): number {\n  const [pid, directory, , portText] = contents.split(\"\\n\");\n  const port = Number(portText);\n  if (Number(pid) !== expectedPid || !directory || resolve(directory) !== resolve(dataDir) ||\n      !Number.isSafeInteger(port) || port < 1 || port > 65535)\n    throw new Error(\"The running embedded PostgreSQL identity does not match this instance. Startup stopped before connecting.\");\n  return port;\n}\n","sourceCodeStart":1,"sourceCodeEnd":13,"githubUrl":"https://github.com/paperclipai/paperclip/blob/3f1d897a7c018d76563a21c6e39c3c9b03933622/server/src/embedded-postgres-owner.ts#L1-L13","documentation":"embeddedPostgresOwnerPort reads the embedded PostgreSQL postmaster PID file and returns the actual port the running instance is listening on after collision avoidance. Before returning, it verifies that the PID, data directory, and port recorded in the file match the current instance's expected PID and dataDir. Any mismatch or out-of-range port means the running PostgreSQL belongs to a different instance, so startup is stopped before connecting to avoid operating on a foreign database.","triggerScenarios":"Calling startServerWithDatabaseTeardown when a postmaster.pid file exists but records a different PID than expected, a data directory path that resolves elsewhere than the configured dataDir, or a port outside 1-65535 (including NaN from a corrupt/truncated pid file).","commonSituations":"Copying or restoring a data/ directory while another Paperclip instance is still running; a stale or hand-edited postmaster.pid; running two instances against the same checkout after a crash; Docker volume reuse across differently-configured containers.","solutions":["Stop the other running Paperclip/PostgreSQL process, then remove the stale postmaster.pid from the data directory before restarting","Point this instance at its own data directory (or reset dev DB with `rm -rf data/pglite` and `pnpm dev`)","If the PID file is corrupt (port NaN), delete the pid file only after confirming no postgres process is alive (`ps aux | grep postgres`)","Run each instance from a distinct workspace/checkout so data dirs do not collide"],"exampleFix":"# before: stale pid file from another instance\nrm -rf data/pglite && pnpm dev","handlingStrategy":"try-catch","validationCode":"const contents = fs.readFileSync(postmasterPidFile, \"utf8\");\nconst [pid, dir, , port] = contents.split(\"\\n\");\nconst ok = Number(pid) === expectedPid && dir && resolve(dir) === resolve(dataDir)\n  && Number.isSafeInteger(Number(port)) && Number(port) >= 1 && Number(port) <= 65535;\nif (!ok) console.error(\"pid file identity mismatch — clean up before starting\");","typeGuard":"function pidFileMatches(contents: string, dataDir: string, expectedPid: number): boolean {\n  const [pid, directory, , portText] = contents.split(\"\\n\");\n  const port = Number(portText);\n  return Number(pid) === expectedPid && Boolean(directory)\n    && resolve(directory) === resolve(dataDir)\n    && Number.isSafeInteger(port) && port >= 1 && port <= 65535;\n}","tryCatchPattern":"try { port = embeddedPostgresOwnerPort(contents, dataDir, expectedPid); }\ncatch (e) {\n  console.error(\"Embedded PostgreSQL identity mismatch; stop the other instance and clear the stale postmaster.pid\", e);\n  process.exit(1);\n}","preventionTips":["Run only one Paperclip instance per data directory","Stop old instances cleanly so postmaster.pid is removed","Never hand-edit or copy postmaster.pid files between workspaces","Reset the dev DB (`rm -rf data/pglite`) when switching branches with schema changes"],"tags":["postgres","embedded","pid-file","startup"],"backgroundTag":"invalid-state-transition","analyzedSha":"3f1d897a7c018d76563a21c6e39c3c9b03933622","analyzedAt":"2026-09-18T08:03:59.046Z","contentChangedAt":"2026-09-18T08:03:59.046Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}