paperclipai/paperclip · error

Embedded PostgreSQL could not find a free port from ${startP

Error message

Embedded PostgreSQL could not find a free port from ${startPort} to ${startPort + maxLookahead - 1}

What it means

Error "Embedded PostgreSQL could not find a free port from ${startPort} to ${startPort + maxLookahead - 1}" thrown in paperclipai/paperclip.

Source

Thrown at packages/db/src/migration-runtime.ts:75

    const server = createServer();
    server.unref();
    server.once("error", (error: NodeJS.ErrnoException) => {
      resolve(error.code === "EADDRINUSE");
    });
    server.listen(port, "127.0.0.1", () => {
      server.close();
      resolve(false);
    });
  });
}

async function findAvailablePort(startPort: number): Promise<number> {
  const maxLookahead = 20;
  let port = startPort;
  for (let i = 0; i < maxLookahead; i += 1, port += 1) {
    if (!(await isPortInUse(port))) return port;
  }
  throw new Error(
    `Embedded PostgreSQL could not find a free port from ${startPort} to ${startPort + maxLookahead - 1}`,
  );
}

async function loadEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
  try {
    const mod = await import("embedded-postgres");
    return mod.default as EmbeddedPostgresCtor;
  } catch {
    throw new Error(
      "Embedded PostgreSQL support requires dependency `embedded-postgres`. Reinstall dependencies and try again.",
    );
  }
}

async function ensureEmbeddedPostgresConnection(
  dataDir: string,
  preferredPort: number,

View on GitHub (pinned to 120ae5428f)

Solutions

1. Free a port in the embedded Postgres scan range or raise the startPort/maxLookahead so a free port exists.
2. Check for stale embedded-postgres processes holding ports (e.g. `lsof -i -P | grep LISTEN`) and stop them.

When it happens

Trigger: Thrown at packages/db/src/migration-runtime.ts:75 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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