mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Argument for maxTimeMS must be a number

Error message

Argument for maxTimeMS must be a number

What it means

Thrown as a MongoInvalidArgumentError from maxTimeMS() when the value argument fails `typeof value !== 'number'`. maxTimeMS sets a server-side time limit on the initial cursor-creating command (find/aggregate/listCollections), encoded as a BSON int32, so a non-number cannot be serialized. The method also requires the cursor not be initialized yet. Note this is the legacy per-command maxTimeMS; with CSOT (timeoutMS) the driver manages maxTimeMS internally.

Solutions

1. Pass a finite number of milliseconds: cursor.maxTimeMS(5000).
2. Parse config strings first: cursor.maxTimeMS(Number(process.env.CURSOR_TIMEOUT_MS)).
3. If migrating to CSOT, set timeoutMS on the cursor options instead and let the driver derive maxTimeMS.

Example fix

// before: string from config
const ms = process.env.MAX_TIME_MS; // '5000'
cursor.maxTimeMS(ms);

// after: parse to a number
cursor.maxTimeMS(Number(process.env.MAX_TIME_MS ?? 5000));

if (typeof value !== 'number' || !Number.isFinite(value)) {
  throw new TypeError('maxTimeMS must be a finite number');
}
cursor.maxTimeMS(value);

function isFiniteNumber(v: unknown): v is number {
  return typeof v === 'number' && Number.isFinite(v);
}

When it happens

Trigger: cursor.maxTimeMS('5000'); cursor.maxTimeMS(undefined); cursor.maxTimeMS(5000n) (BigInt is not a number).

Common situations: Reading timeout values from env/config as strings and passing them unconverted; mixing BigInt timestamps with millisecond numbers; passing a value typed as string|number without narrowing.

Related errors

• Argument "iterator" must be a function
• Flag is not one of
• Flag must be a boolean value
• Invalid read preference
• Operation "batchSize" requires an integer

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

Appendix: source

Thrown at src/cursor/abstract_cursor.ts:789

  withReadConcern(readConcern: ReadConcernLike): this {
    this.throwIfInitialized();
    const resolvedReadConcern = ReadConcern.fromOptions({ readConcern });
    if (resolvedReadConcern) {
      this.cursorOptions.readConcern = resolvedReadConcern;
    }

    return this;
  }

  /**
   * Set a maxTimeMS on the cursor query, allowing for hard timeout limits on queries (Only supported on MongoDB 2.6 or higher)
   *
   * @param value - Number of milliseconds to wait before aborting the query.
   */
  maxTimeMS(value: number): this {
    this.throwIfInitialized();
    if (typeof value !== 'number') {
      throw new MongoInvalidArgumentError('Argument for maxTimeMS must be a number');
    }

    this.cursorOptions.maxTimeMS = value;
    return this;
  }

  /**
   * Set the batch size for the cursor.
   *
   * @param value - The number of documents to return per batch. See {@link https://www.mongodb.com/docs/manual/reference/command/find/|find command documentation}.
   */
  batchSize(value: number): this {
    this.throwIfInitialized();
    if (this.cursorOptions.tailable) {
      throw new MongoTailableCursorError('Tailable cursor does not support batchSize');
    }

    if (typeof value !== 'number') {

View on GitHub (pinned to dce7939f86)