mongodb/node-mongodb-native · error · MongoOperationTimeoutError

Timed out during connection checkout

Error message

Timed out during connection checkout

What it means

A MongoOperationTimeoutError thrown in ConnectionPool.checkOut when CSOT is enabled and the wait-queue timeout fires before a connection becomes available. The underlying WaitQueueTimeoutError is attached as cause. Under CSOT the checkout timeout is derived from the operation's timeoutMS; when it expires, the driver raises this unified timeout error instead of the legacy WaitQueueTimeoutError.

Solutions

1. Increase maxPoolSize to match peak concurrency.
2. Increase timeoutMS to allow more wait time for a connection.
3. Audit for connection leaks — ensure cursors and sessions are closed/iterated to completion.
4. Reduce per-operation hold time (faster queries, indexes) so connections recycle faster.

Example fix

// before
const client = new MongoClient(uri, { maxPoolSize: 5, timeoutMS: 1000 });

// after
const client = new MongoClient(uri, { maxPoolSize: 50, timeoutMS: 10000 });

// Sanity check pool sizing vs. expected concurrency
const expectedConcurrency = 100;
if (maxPoolSize < expectedConcurrency && timeoutMS < 5000) {
  // either grow the pool or widen the timeout
  maxPoolSize = expectedConcurrency;
}

try {
  await operation();
} catch (e) {
  if (e instanceof MongoOperationTimeoutError && /connection checkout/i.test(e.message)) {
    // transient pool exhaustion — back off and retry
  } else throw e;
}

When it happens

Trigger: All connections are checked out and the operation's CSOT budget (timeoutMS) expires while waiting in the pool's wait queue. Triggered by sustained concurrency exceeding maxPoolSize under CSOT.

Common situations: maxPoolSize too low for the workload; long-running queries holding connections; connection leaks (connections not returned); spikes in concurrent requests under a tight timeoutMS.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• An operation cannot be given a timeoutMS setting when…
• Cannot set timeoutMode without setting timeoutMS
• Cannot specify maxAwaitTimeMS >= timeoutMS for a tailable…
• Cannot use maxTimeMS with timeoutMS for explain commands.
• Expired after ms

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/cba67b4307350ea0. Report an issue: GitHub.

Appendix: 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 dce7939f86)