abhigyanpatwari/GitNexus · error · Error

Connection pool integrity error: expected ${MAX_CONNS_PER_RE

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

Thrown by the checkout() function when a pool entry has fewer total connections (available + checkedOut) than MAX_CONNS_PER_REPO (8). The pool is pre-warmed to MAX_CONNS_PER_REPO during init; if checkout finds the available list empty AND total connections below the cap, a connection was leaked — it was checked out and never returned. Rather than silently creating a replacement (which would mask the leak and could silence stdout mid-query), the error surfaces the bug with the exact available/checkedOut counts.

Source

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

/**
 * 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 d540b00184)

Solutions

This is an internal bug, not a configuration issue — report it with the full stack trace showing the checkout/checkin imbalance
Re-run `gitnexus analyze` to recreate the pool from scratch (the pool is per-process and per-repoId)
As a workaround, restart the `gitnexus serve` or MCP process to reset the connection pool
Review the GitNexus version — this may be fixed in a newer release; check the changelog for pool-leak fixes

Defensive patterns

Strategy: try-catch

Try / catch

try {
  const conn = await checkout(entry);
  // ... use conn ...
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Connection pool integrity')) {
    // Internal bug — restart the process to reset the pool
    logger.error('Connection pool leak detected — restart the process', e);
  }
  throw e;
} finally {
  // Always ensure checkin runs — this is what prevents the leak
  if (conn) await checkin(entry, conn);
}

Prevention

Always wrap checkout/checkin in try/finally to guarantee connection return on all code paths
Never store a checked-out connection in a long-lived variable that might not be returned
Monitor checkedOut vs available counts in production to detect slow leaks
Report recurring pool integrity errors as bugs — they indicate a missing checkin path

When it happens

Trigger: A code path in the pool adapter or its callers that calls checkout() but doesn't always call checkin() — e.g. an early return, an unhandled rejection, or an exception between checkout and checkin that bypasses the finally block. Each leaked connection reduces totalConns by one; once it drops below 8, this error fires on the next checkout when the available list is also empty.

Common situations: A bug in a query helper that returns early without releasing the connection; a Promise rejection that isn't caught in the try/finally that wraps checkout/checkin; a race condition where checkin runs on a different pool entry than checkout (e.g. after an LRU eviction); an uncaught error in closeQueryResults that prevents the finally block from completing checkin.

Related errors

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