mongodb/node-mongodb-native · error · MongoOperationTimeoutError

Timed out during connection checkout

Error message

Timed out during connection checkout

What it means

Thrown in ConnectionPool.checkOut (src/cmap/connection_pool.ts:365-369) when CSOT (timeoutMS) is enabled and the wait queue timed out waiting for a free connection. Without CSOT the same condition throws a plain WaitQueueTimeoutError; with CSOT the driver re-wraps it as MongoOperationTimeoutError so it composes correctly with the operation's overall timeout semantics.

Source

Thrown at src/cmap/connection_pool.ts:366

      timeout?.throwIfExpired();
      return await (timeout ? Promise.race([promise, timeout]) : promise);
    } catch (error) {
      if (TimeoutError.is(error)) {
        timeout?.clear();
        waitQueueMember.cancelled = true;

        this.emitAndLog(
          ConnectionPool.CONNECTION_CHECK_OUT_FAILED,
          new ConnectionCheckOutFailedEvent(this, 'timeout', waitQueueMember.checkoutTime)
        );
        const timeoutError = new WaitQueueTimeoutError(
          this.loadBalanced
            ? this.waitQueueErrorMetrics()
            : 'Timed out while checking out a connection from connection pool',
          this.address
        );
        if (options.timeoutContext.csotEnabled()) {
          throw new MongoOperationTimeoutError('Timed out during connection checkout', {
            cause: timeoutError
          });
        }
        throw timeoutError;
      }
      throw error;
    } finally {
      abortListener?.[kDispose]();
      timeout?.clear();
    }
  }

  /**
   * Check a connection into the pool.
   *
   * @param connection - The connection to check in
   */
  checkIn(connection: Connection): void {

View on GitHub (pinned to 3366c21a63)

Solutions

1. Increase maxPoolSize to match peak concurrency.
2. Increase timeoutMS so the operation can survive brief pool contention.
3. Find and fix connection leaks - ensure cursors and sessions are always closed (return connections to the pool).
4. Tune maxConnecting (default 2) upward if the bottleneck is connection setup rather than steady-state usage.

Example fix

// before
new MongoClient(uri, { maxPoolSize: 5, timeoutMS: 50 });

// after
new MongoClient(uri, { maxPoolSize: 50, timeoutMS: 1000 });

function validatePoolCapacityForConcurrency(maxPoolSize: number, peakConcurrency: number, timeoutMS: number) {
  if (maxPoolSize < peakConcurrency) {
    console.warn(`maxPoolSize ${maxPoolSize} < peak concurrency ${peakConcurrency}; checkout waits likely`);
  }
}

import { MongoOperationTimeoutError } from 'mongodb';
function isCheckoutTimeout(e: unknown): e is MongoOperationTimeoutError {
  return e instanceof MongoOperationTimeoutError &&
    /connection checkout/i.test(e.message);
}

import { MongoOperationTimeoutError } from 'mongodb';
async function withCheckoutRetry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
  for (let i = 0; i < attempts; i++) {
    try { return await fn(); }
    catch (e) {
      if (e instanceof MongoOperationTimeoutError && /connection checkout/i.test(e.message) && i < attempts - 1) {
        await new Promise(r => setTimeout(r, 50 * (i + 1))); continue;
      }
      throw e;
    }
  }
  throw new Error('unreachable');
}

When it happens

Trigger: All connections in the pool are checked out and busy, the operation's timeoutMS budget expires while waiting in the pool's waitQueue, and timeoutContext.csotEnabled() is true. Triggered on any operation whose connection checkout races the per-op timeout.

Common situations: maxPoolSize too small for the workload's concurrency; long-running queries holding connections; spike in request rate saturating the pool; timeoutMS set lower than typical checkout wait time; connection leaks (checked-out connections never returned) shrinking the effective pool.

Related errors

• KMS request timed out
• Server roundtrip time is greater than the time remaining
• Server reported a timeout error
• Cannot specify maxAwaitTimeMS >= timeoutMS for a tailable aw
• Cannot set tailable cursor's timeoutMode to LIFETIME

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/cba67b4307350ea0.json. Report an issue: GitHub.