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 by cursor.maxTimeMS(value) when value is not of type 'number'. maxTimeMS sets a server-side time limit (pre-CSOT API) and must be a numeric millisecond value; strings, BigInt, and undefined are rejected.

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 3366c21a63)

Solutions

1. Coerce: maxTimeMS(Number(value)).
2. If using CSOT/timeoutMS, remove maxTimeMS entirely.
3. Validate the source is numeric before calling.

Example fix

// before
cursor.maxTimeMS(process.env.MAX_MS); // string
// after
cursor.maxTimeMS(Number(process.env.MAX_MS));

if (typeof value !== 'number') throw new TypeError('maxTimeMS must be a number');
cursor.maxTimeMS(value);

function isNumber(v): v is number { return typeof v === 'number' && !Number.isNaN(v); }

When it happens

Trigger: Calling maxTimeMS('5000'), maxTimeMS(BigInt(5000)), maxTimeMS(undefined), or maxTimeMS(process.env.MAX_MS) where the env var is a string. Note: when using CSOT (timeoutMS), maxTimeMS is managed automatically and should not be set.

Common situations: Reading the value from an env var or JSON config (always strings); mixing BigInt from a config parser; setting maxTimeMS while also using timeoutMS (the latter supersedes it).

Related errors

• Cannot specify maxAwaitTimeMS >= timeoutMS for a tailable aw
• Cannot set tailable cursor's timeoutMode to LIFETIME
• Cannot set timeoutMode without setting timeoutMS
• Flag ${flag} must be a boolean value
• Invalid read preference: ${readPreference}

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