paperclipai/paperclip · error

Embedded PostgreSQL port is in use; using next free port (re

Error message

Embedded PostgreSQL port is in use; using next free port (requestedPort=${configuredPort}, selectedPort=${detectedPort})

What it means

Startup warning (logger.warn) in startServer. Fires when the configured embedded PostgreSQL port is occupied by an unrelated/foreign server (data directory mismatch or bind failure), so the resolver picks the next free port and proceeds with it.

Source

Thrown at server/src/index.ts:522

        return pid;
      } catch {
        return null;
      }
    };
  
    const runningPid = getRunningPid();
    if (runningPid) {
      logger.warn(`Embedded PostgreSQL already running; reusing existing process (pid=${runningPid}, port=${port})`);
    } else {
      const configuredAdminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${configuredPort}/postgres`;
      try {
        const actualDataDir = await getPostgresDataDirectory(configuredAdminConnectionString);
        if (
          typeof actualDataDir !== "string" ||
          resolve(actualDataDir) !== resolve(dataDir)
        ) {
          throw new Error("reachable postgres does not use the expected embedded data directory");
        }
        await ensurePostgresDatabase(configuredAdminConnectionString, "paperclip");
        logger.warn(
          `Embedded PostgreSQL appears to already be reachable without a pid file; reusing existing server on configured port ${configuredPort}`,
        );
      } catch {
        const detectedPort = await detectPort(configuredPort);
        if (detectedPort !== configuredPort) {
          logger.warn(`Embedded PostgreSQL port is in use; using next free port (requestedPort=${configuredPort}, selectedPort=${detectedPort})`);
        }
        port = detectedPort;
        logger.info(`Using embedded PostgreSQL because no DATABASE_URL set (dataDir=${dataDir}, port=${port})`);
        const createEmbeddedPostgres = () => new EmbeddedPostgres({
          databaseDir: dataDir,
          user: "paperclip",
          password: "paperclip",
          port,
          persistent: true,
          initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],

View on GitHub (pinned to 01ad858492)

Solutions

1. No action needed; a free port was selected automatically.
2. To use a fixed port, free the configured port or update the embedded PostgreSQL port configuration.

When it happens

Trigger: Thrown at server/src/index.ts:449 when the library encounters an invalid state.

Common situations: Logged at startup when the configured embedded PostgreSQL port is already in use, so the next free port is chosen.

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