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() (MongoInvalidArgumentError) when value is not a number. maxTimeMS sets the server-side time limit for the initial find command; non-numeric input (string, undefined, object) is rejected before being sent.

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

Solutions

1. Coerce and validate: const ms = Number(val); if (Number.isFinite(ms)) cursor.maxTimeMS(ms)
2. Type your config objects so maxTimeMS is number
3. Use timeoutMS (the newer API) with a validated number instead

Example fix

// before
cursor.maxTimeMS(cfg.timeoutStr);
// after
cursor.maxTimeMS(Number(cfg.timeoutStr));

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

const isFiniteNumber = (v) => typeof v === 'number' && Number.isFinite(v);

When it happens

Trigger: cursor.maxTimeMS('500'), cursor.maxTimeMS(undefined), cursor.maxTimeMS(config.maxTimeMS) where config field is a string.

Common situations: Config/env-driven timeouts parsed as strings; spreading an options object typed as any; copy-paste from JSON config.

Related errors

• Argument for maxAwaitTimeMS must be a number
• Operation "limit" requires an integer
• Operation "skip" requires an integer
• Option "keyAltNames" must be an array of strings, but was of
• Option "keyAltNames" must be an array of strings, but item a

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