Connection pool integrity error: expected

Error message

Connection pool integrity error: expected ${MAX_CONNS_PER_REPO} connections but found ${totalConns} (${entry.available.length} available, ${entry.checkedOut} checked out)

What it means

checkout (gitnexus/src/core/lbug/pool-adapter.ts:941): the pool is pre-warmed to MAX_CONNS_PER_REPO connections at init, so finding available + checkedOut below that total means a connection was checked out and never checked back in — a leak. The guard throws rather than silently creating a replacement, because lazy connection creation would corrupt stdout handling mid-query.

Solutions

Report it as a GitNexus bug with the stack — this is an internal accounting invariant, not a user misconfiguration
Restart the MCP/serve process: a fresh initLbug rebuilds the pool at full size
Upgrade to the latest GitNexus patch in case the leak is already fixed
Note which query preceded the first occurrence and include it in the report

Defensive patterns

Strategy: try-catch

Type guard

const isPoolIntegrityError = (e: unknown): boolean =>
  e instanceof Error && e.message.startsWith('Connection pool integrity error:');

Try / catch

try {
  rows = await executeParameterized(repoId, cypher, params);
} catch (e) {
  if (isPoolIntegrityError(e)) {
    // leaked connection — the pool cannot heal itself; recycle the process and report
    logger.error(`${e.message} — restarting MCP/serve process; report as a GitNexus bug`);
    await scheduleProcessRestart();
  }
  throw e;
}

Prevention

Always return pooled connections via try/finally checkin — never early-return around a checkout
Keep GitNexus patched — pool accounting fixes land in patch releases
Restart long-lived MCP servers periodically if this leak is observed in your version

When it happens

Trigger: Any executeParameterized call on a repo pool where an earlier call leaked its connection — a code path that took the conn outside the try/finally that performs checkin, or a native error that invalidated a connection without the pool's accounting noticing.

Common situations: A GitNexus regression dropping the finally-checkin; native LadybugDB failures that close a connection underneath the pool; long-lived MCP servers that hit the leak after N queries and then fail every query on that repo.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@ac9a4e9abd (2026-08-20). Data as JSON: /api/errors/2ebadd1483e34531. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/core/lbug/pool-adapter.ts:1165

/**
 * Checkout a connection from the pool.
 * Returns an available connection, or creates a new one if under the cap.
 * If all connections are busy and at cap, queues the caller until one is returned.
 */
function checkout(entry: PoolEntry): Promise<lbug.Connection> {
  // Fast path: grab an available connection
  if (entry.available.length > 0) {
    entry.checkedOut++;
    return Promise.resolve(entry.available.pop()!);
  }

  // Pool was pre-warmed to MAX_CONNS_PER_REPO during init.  If we're here
  // with fewer total connections, something leaked — surface the bug rather
  // than silently creating a connection (which would silence stdout mid-query).
  const totalConns = entry.available.length + entry.checkedOut;
  if (totalConns < MAX_CONNS_PER_REPO) {
    throw new Error(
      `Connection pool integrity error: expected ${MAX_CONNS_PER_REPO} ` +
        `connections but found ${totalConns} (${entry.available.length} available, ` +
        `${entry.checkedOut} checked out)`,
    );
  }

  // At capacity — queue the caller with a timeout.
  return new Promise<lbug.Connection>((resolve, reject) => {
    const waiter = {
      resolve: (conn: lbug.Connection) => {
        clearTimeout(timer);
        resolve(conn);
      },
      reject: (err: Error) => {
        clearTimeout(timer);
        reject(err);
      },
    };

View on GitHub (pinned to ac9a4e9abd)