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 FindCursor.maxTimeMS when its argument is not of type 'number'. maxTimeMS sets a server-side deadline on the find command; the driver validates the type before storing it on findOptions. Strings, booleans, undefined, or objects are rejected.

Solutions

1. Coerce and validate: const ms = Number(value); if (!Number.isFinite(ms)) throw ...; cursor.maxTimeMS(ms).
2. Use the typed option in the find call: collection.find({}, { maxTimeMS: 5000 }).
3. Check for NaN explicitly because typeof NaN === 'number' passes the guard but is invalid downstream.

Example fix

// before
const ms = parseInt(input); // NaN if input is bad
cursor.maxTimeMS(ms);

// after
const ms = Number(input);
if (!Number.isFinite(ms)) throw new Error('maxTimeMS must be a finite number');
cursor.maxTimeMS(ms);

function setMaxTimeMS(cursor, value) {
  const ms = Number(value);
  if (!Number.isFinite(ms)) throw new TypeError('maxTimeMS must be a finite number');
  return cursor.maxTimeMS(ms);
}

function isFinitePositiveNumber(v) {
  return typeof v === 'number' && Number.isFinite(v) && v > 0;
}

When it happens

Trigger: cursor.maxTimeMS('5000'); cursor.maxTimeMS(parseInt(value)) where parseInt returned NaN; passing a config value typed as string | number without narrowing.

Common situations: Environment-variable-derived timeouts (strings); parseInt/Number returning NaN on bad input; spreading an options object whose maxTimeMS field is incorrectly typed.

Related errors

• Argument for maxAwaitTimeMS must be a number
• Operation "limit" requires an integer
• Operation "skip" requires an integer
• timeoutMS cannot be used with explain when explain is…
• An operation cannot be given a timeoutMS setting when…

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

Appendix: source

Thrown at src/cursor/find_cursor.ts:357

  maxAwaitTimeMS(value: number): this {
    this.throwIfInitialized();
    if (typeof value !== 'number') {
      throw new MongoInvalidArgumentError('Argument for maxAwaitTimeMS must be a number');
    }

    this.findOptions.maxAwaitTimeMS = value;
    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.
   */
  override maxTimeMS(value: number): this {
    this.throwIfInitialized();
    if (typeof value !== 'number') {
      throw new MongoInvalidArgumentError('Argument for maxTimeMS must be a number');
    }

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

  /**
   * Add a project stage to the aggregation pipeline
   *
   * @remarks
   * In order to strictly type this function you must provide an interface
   * that represents the effect of your projection on the result documents.
   *
   * By default chaining a projection to your cursor changes the returned type to the generic
   * {@link Document} type.
   * You should specify a parameterized type to have assertions on your final results.
   *
   * @example

View on GitHub (pinned to dce7939f86)