{"record":{"id":"044c96a4ace7c353","repo":"paperclipai/paperclip","slug":"invalid-running-embedded-database-port","errorCode":null,"errorMessage":"Invalid running embedded database port","messagePattern":"Invalid running embedded database port","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/db/scripts/create-auth-bootstrap-invite.ts","lineNumber":50,"sourceCode":"      mode?: string;\n      embeddedPostgresPort?: number;\n      embeddedPostgresDataDir?: string;\n      connectionString?: string;\n    };\n  };\n  // The server can select another port when the configured one is occupied.\n  // Bind bootstrap to this data directory's running process, never another instance.\n  let embeddedPort: number | undefined;\n  if (config.database?.mode !== \"postgres\") {\n    const dataDir = config.database?.embeddedPostgresDataDir;\n    if (!dataDir) throw new Error(\"Embedded bootstrap requires its configured data directory\");\n    const pidLines = readFileSync(path.join(dataDir, \"postmaster.pid\"), \"utf8\").split(/\\r?\\n/);\n    if (realpathSync(pidLines[1] ?? \"\") !== realpathSync(dataDir)) throw new Error(\"Embedded bootstrap data directory does not match the running postmaster\");\n    const postmasterPid = Number(pidLines[0]);\n    if (!Number.isInteger(postmasterPid) || postmasterPid <= 1) throw new Error(\"Invalid embedded postmaster PID\");\n    process.kill(postmasterPid, 0);\n    embeddedPort = Number(pidLines[3]);\n    if (!Number.isInteger(embeddedPort) || embeddedPort < 1 || embeddedPort > 65535) throw new Error(\"Invalid running embedded database port\");\n  }\n  const dbUrl =\n    config.database?.mode === \"postgres\"\n      ? config.database.connectionString\n      : `postgres://paperclip:paperclip@127.0.0.1:${embeddedPort}/paperclip`;\n  if (!dbUrl) {\n    throw new Error(`Could not resolve database connection from ${configPath}`);\n  }\n\n  const db = createDb(dbUrl);\n  const closableDb = db as typeof db & {\n    $client?: {\n      end?: (options?: { timeout?: number }) => Promise<void>;\n    };\n  };\n\n  try {\n    const now = new Date();","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/paperclipai/paperclip/blob/3f1d897a7c018d76563a21c6e39c3c9b03933622/packages/db/scripts/create-auth-bootstrap-invite.ts#L32-L68","documentation":"Thrown by create-auth-bootstrap-invite when line 4 of the embedded PostgreSQL postmaster.pid file (the TCP port postmaster is listening on) is not an integer in the valid port range 1-65535. The script trusts this line to build the postgres:// connection URL for the embedded database, so an unusable port means the pid file is stale, corrupt, or from a layout it does not understand, and it aborts instead of connecting to the wrong instance.","triggerScenarios":"Running the bootstrap script in embedded mode (config.database.mode !== \"postgres\") where <embeddedPostgresDataDir>/postmaster.pid has fewer than 5 lines (so pidLines[3] is undefined) or a fourth line that Number() cannot turn into an integer between 1 and 65535.","commonSituations":"Embedded Postgres crashed mid-write leaving a truncated pid file; the data directory belongs to an older/different PostgreSQL layout; a leftover pid file from an instance that already exited; pointing embeddedPostgresDataDir at a partially initialized or manually copied directory.","solutions":["Confirm the embedded database is running for this exact data directory (start it with `pnpm dev`) so a complete postmaster.pid exists","Delete the stale/truncated postmaster.pid and restart the embedded database so it regenerates a full pid file","Reset the embedded data directory if it is expendable: `rm -rf data/pglite && pnpm dev`, then rerun the script","Switch the config to database.mode \"postgres\" with a connectionString to bypass pid-file parsing entirely"],"exampleFix":"// inspect the pid file\n// cat ./data/pglite/postmaster.pid  # line 1=PID, 2=datadir, 4=port\n// before (config.json)\n{ \"database\": { \"mode\": \"embedded\", \"embeddedPostgresDataDir\": \"./stale-dir\" } }\n// after\n{ \"database\": { \"mode\": \"embedded\", \"embeddedPostgresDataDir\": \"./data/pglite\" } }","handlingStrategy":"validation","validationCode":"import { readFileSync } from \"node:fs\";\nconst pidLines = readFileSync(`${dataDir}/postmaster.pid`, \"utf8\").split(/\\r?\\n/);\nconst port = Number(pidLines[3]);\nif (!Number.isInteger(port) || port < 1 || port > 65535) {\n  throw new Error(`postmaster.pid line 4 is not a valid port: ${pidLines[3]}`);\n}","typeGuard":"function isValidPort(v: unknown): v is number {\n  return typeof v === \"number\" && Number.isInteger(v) && v >= 1 && v <= 65535;\n}","tryCatchPattern":"try {\n  await runBootstrapInvite(configPath, baseUrl);\n} catch (err) {\n  if (err instanceof Error && err.message === \"Invalid running embedded database port\") {\n    // pid file truncated/stale: restart embedded postgres, then retry\n    await restartEmbeddedPostgres(dataDir);\n    await runBootstrapInvite(configPath, baseUrl);\n  } else throw err;\n}","preventionTips":["Verify the pid file has at least 5 lines before relying on it (cat <dataDir>/postmaster.pid)","Point embeddedPostgresDataDir at the live data directory the server actually uses","Avoid copying data directories while the postmaster is running; stop it first","Prefer database.mode=postgres + connectionString when you do not depend on embedded Postgres"],"tags":["database","embedded-postgres","port","config"],"backgroundTag":"invalid-config-value","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"}