{"record":{"id":"72f5408cb16e1139","repo":"paperclipai/paperclip","slug":"embedded-postgresql-could-not-find-a-free-port-fro","errorCode":null,"errorMessage":"Embedded PostgreSQL could not find a free port from ${startPort} to ${startPort + maxLookahead - 1}","messagePattern":"Embedded PostgreSQL could not find a free port from (.+?) to (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/db/src/migration-runtime.ts","lineNumber":75,"sourceCode":"    const server = createServer();\n    server.unref();\n    server.once(\"error\", (error: NodeJS.ErrnoException) => {\n      resolve(error.code === \"EADDRINUSE\");\n    });\n    server.listen(port, \"127.0.0.1\", () => {\n      server.close();\n      resolve(false);\n    });\n  });\n}\n\nasync function findAvailablePort(startPort: number): Promise<number> {\n  const maxLookahead = 20;\n  let port = startPort;\n  for (let i = 0; i < maxLookahead; i += 1, port += 1) {\n    if (!(await isPortInUse(port))) return port;\n  }\n  throw new Error(\n    `Embedded PostgreSQL could not find a free port from ${startPort} to ${startPort + maxLookahead - 1}`,\n  );\n}\n\nasync function loadEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {\n  try {\n    const mod = await import(\"embedded-postgres\");\n    return mod.default as EmbeddedPostgresCtor;\n  } catch {\n    throw new Error(\n      \"Embedded PostgreSQL support requires dependency `embedded-postgres`. Reinstall dependencies and try again.\",\n    );\n  }\n}\n\nasync function ensureEmbeddedPostgresConnection(\n  dataDir: string,\n  preferredPort: number,","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/paperclipai/paperclip/blob/120ae5428fa29bee300bcf806491cd4d965fbb7c/packages/db/src/migration-runtime.ts#L57-L93","documentation":"Error \"Embedded PostgreSQL could not find a free port from ${startPort} to ${startPort + maxLookahead - 1}\" thrown in paperclipai/paperclip.","triggerScenarios":"Thrown at packages/db/src/migration-runtime.ts:75 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Free a port in the embedded Postgres scan range or raise the startPort/maxLookahead so a free port exists.","Check for stale embedded-postgres processes holding ports (e.g. `lsof -i -P | grep LISTEN`) and stop them."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"120ae5428fa29bee300bcf806491cd4d965fbb7c","analyzedAt":"2026-08-18T22:49:45.177Z","contentChangedAt":"2026-08-18T22:49:45.177Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}