mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Connection pool minimum size must not be greater than maximu

Error message

Connection pool minimum size must not be greater than maximum pool size

What it means

Thrown in the ConnectionPool constructor (src/cmap/connection_pool.ts:210-214) when minPoolSize exceeds maxPoolSize. The pool enforces this invariant at construction because a minimum larger than the maximum is logically impossible and would leave the pool perpetually trying to grow. Maps to MongoInvalidArgumentError.

Source

Thrown at src/cmap/connection_pool.ts:211

  constructor(server: Server, options: ConnectionPoolOptions) {
    super();
    this.on('error', noop);

    this.options = Object.freeze({
      connectionType: Connection,
      ...options,
      maxPoolSize: options.maxPoolSize ?? 100,
      minPoolSize: options.minPoolSize ?? 0,
      maxConnecting: options.maxConnecting ?? 2,
      maxIdleTimeMS: options.maxIdleTimeMS ?? 0,
      waitQueueTimeoutMS: options.waitQueueTimeoutMS ?? 0,
      minPoolSizeCheckFrequencyMS: options.minPoolSizeCheckFrequencyMS ?? 100,
      autoEncrypter: options.autoEncrypter
    });

    if (this.options.minPoolSize > this.options.maxPoolSize) {
      throw new MongoInvalidArgumentError(
        'Connection pool minimum size must not be greater than maximum pool size'
      );
    }

    this.poolState = PoolState.paused;
    this.server = server;
    this.connections = new List();
    this.pending = 0;
    this.checkedOut = new Set();
    this.minPoolSizeTimer = undefined;
    this.generation = 0;
    this.serviceGenerations = new Map();
    this.connectionCounter = makeCounter(1);
    this.cancellationToken = new CancellationToken();
    this.cancellationToken.setMaxListeners(Infinity);
    this.waitQueue = new List();
    this.metrics = new ConnectionPoolMetrics();
    this.processingWaitQueue = false;

View on GitHub (pinned to 3366c21a63)

Solutions

1. Ensure minPoolSize <= maxPoolSize; commonly set min to a fraction of max (e.g. min=10, max=100).
2. If you only want a floor, leave maxPoolSize at its default (100) and set only minPoolSize.
3. Audit environment-variable-driven config that injects these values independently.
4. Drop minPoolSize entirely if you do not need a warm pool - the default 0 is valid.

Example fix

// before
new MongoClient(uri, { minPoolSize: 50, maxPoolSize: 20 });

// after
new MongoClient(uri, { minPoolSize: 10, maxPoolSize: 50 });

function validatePoolSizes(min: number, max: number) {
  if (min > max) {
    throw new Error(`minPoolSize (${min}) must not exceed maxPoolSize (${max})`);
  }
  if (min < 0 || max < 0) throw new Error('pool sizes must be non-negative');
}

function areValidPoolSizes(min: unknown, max: unknown): boolean {
  return typeof min === 'number' && typeof max === 'number' &&
    min >= 0 && max >= 0 && min <= max;
}

import { MongoInvalidArgumentError } from 'mongodb';
try {
  const c = new MongoClient(uri, { minPoolSize, maxPoolSize });
  await c.connect();
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /pool/i.test(e.message)) {
    // swap or drop the offending value and recreate
  }
  throw e;
}

When it happens

Trigger: Constructing MongoClient with { minPoolSize: N, maxPoolSize: M } where N > M, or the equivalent URI options (?minPoolSize=N&maxPoolSize=M). Fires immediately during MongoClient.connect() / first pool creation.

Common situations: Copy-pasting pool sizing from a sample where the values were swapped; setting minPoolSize to 'keep connections warm' but leaving maxPoolSize at a lower default; environment-specific config overrides that set min without adjusting max; misreading docs (minPoolSize default is 0, maxPoolSize default is 100).

Related errors

• maxConnecting must be > 0 if specified
• Cannot set both proxyOptions and kmsConnectCallback
• Can only provide a custom AWS credential provider when the s
• `cryptSharedLibRequired` set but no crypt_shared library loa
• Cannot set both proxyOptions and kmsConnectCallback

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