{"record":{"id":"2ebadd1483e34531","repo":"abhigyanpatwari/GitNexus","slug":"connection-pool-integrity-error-expected-max-co","errorCode":null,"errorMessage":"Connection pool integrity error: expected ${MAX_CONNS_PER_REPO} connections but found ${totalConns} (${entry.available.length} available, ${entry.checkedOut} checked out)","messagePattern":"Connection pool integrity error: expected (.+?) connections but found (.+?) \\((.+?) available, (.+?) checked out\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/lbug/pool-adapter.ts","lineNumber":941,"sourceCode":"\n/**\n * Checkout a connection from the pool.\n * Returns an available connection, or creates a new one if under the cap.\n * If all connections are busy and at cap, queues the caller until one is returned.\n */\nfunction checkout(entry: PoolEntry): Promise<lbug.Connection> {\n  // Fast path: grab an available connection\n  if (entry.available.length > 0) {\n    entry.checkedOut++;\n    return Promise.resolve(entry.available.pop()!);\n  }\n\n  // Pool was pre-warmed to MAX_CONNS_PER_REPO during init.  If we're here\n  // with fewer total connections, something leaked — surface the bug rather\n  // than silently creating a connection (which would silence stdout mid-query).\n  const totalConns = entry.available.length + entry.checkedOut;\n  if (totalConns < MAX_CONNS_PER_REPO) {\n    throw new Error(\n      `Connection pool integrity error: expected ${MAX_CONNS_PER_REPO} ` +\n        `connections but found ${totalConns} (${entry.available.length} available, ` +\n        `${entry.checkedOut} checked out)`,\n    );\n  }\n\n  // At capacity — queue the caller with a timeout.\n  return new Promise<lbug.Connection>((resolve, reject) => {\n    const waiter = {\n      resolve: (conn: lbug.Connection) => {\n        clearTimeout(timer);\n        resolve(conn);\n      },\n      reject: (err: Error) => {\n        clearTimeout(timer);\n        reject(err);\n      },\n    };","sourceCodeStart":923,"sourceCodeEnd":959,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/lbug/pool-adapter.ts#L923-L959","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  const conn = await checkout(entry);\n  // ... use conn ...\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Connection pool integrity')) {\n    // Internal bug — restart the process to reset the pool\n    logger.error('Connection pool leak detected — restart the process', e);\n  }\n  throw e;\n} finally {\n  // Always ensure checkin runs — this is what prevents the leak\n  if (conn) await checkin(entry, conn);\n}","preventionTips":["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"],"tags":["ladybugdb","connection-pool","leak","pool-adapter","internal-bug"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}