mongodb/node-mongodb-native · error · MongoInvalidArgumentError

maxConnecting must be > 0 if specified

Error message

maxConnecting must be > 0 if specified

What it means

`maxConnecting` caps how many connections the pool may set up concurrently per server (default 2). The transform at src/connection_string.ts:898 parses the value as an unsigned int via getUIntFromOptions, then at src/connection_string.ts:900 throws MongoInvalidArgumentError when the result is exactly 0. Other negative/non-int values fail earlier in getUIntFromOptions.

Solutions

1. Omit `maxConnecting` to accept the default of 2.
2. Pass a positive integer such as `maxConnecting: 10`.
3. Fix config loading so an unset value stays `undefined` rather than becoming `0`.

Example fix

// before
new MongoClient(uri, { maxConnecting: 0 });

// after
new MongoClient(uri, { maxConnecting: 10 });

if (opts.maxConnecting !== undefined) {
  const n = Number(opts.maxConnecting);
  if (!Number.isInteger(n) || n <= 0) throw new Error('maxConnecting must be a positive integer');
}

function isPositiveInt(v: unknown): v is number { return typeof v === 'number' && Number.isInteger(v) && v > 0; }

try { client = new MongoClient(uri, opts); } catch (e) { if (e instanceof MongoInvalidArgumentError && /maxConnecting/.test(e.message)) { delete opts.maxConnecting; client = new MongoClient(uri, opts); } else throw e; }

When it happens

Trigger: Passing `maxConnecting: 0` (e.g. to mean 'no limit' or 'disabled'); reading the value from config where unset becomes 0 instead of undefined; copying the convention from `maxPoolSize` where 0 is treated as unlimited.

Common situations: Config templates that initialize all numeric pool options to 0; operators assuming 0 disables the cap; copying from maxPoolSize semantics.

Related errors

• Auth mechanism property ALLOWED_HOSTS must be an array of…
• AuthContext must provide credentials.
• AuthContext must provide credentials.
• AuthContext must provide credentials.
• AuthContext must provide credentials.

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

Appendix: source

Thrown at src/connection_string.ts:901

  },
  loadBalanced: {
    default: false,
    type: 'boolean'
  },
  localThresholdMS: {
    default: 15,
    type: 'uint'
  },
  maxAdaptiveRetries: {
    default: 2,
    type: 'uint'
  },
  maxConnecting: {
    default: 2,
    transform({ name, values: [value] }): number {
      const maxConnecting = getUIntFromOptions(name, value);
      if (maxConnecting === 0) {
        throw new MongoInvalidArgumentError('maxConnecting must be > 0 if specified');
      }
      return maxConnecting;
    }
  },
  maxIdleTimeMS: {
    default: 0,
    type: 'uint'
  },
  maxPoolSize: {
    default: 100,
    type: 'uint'
  },
  maxStalenessSeconds: {
    target: 'readPreference',
    transform({ name, options, values: [value] }) {
      const maxStalenessSeconds = getUIntFromOptions(name, value);
      if (options.readPreference) {
        return ReadPreference.fromOptions({

View on GitHub (pinned to dce7939f86)