mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Argument for maxAwaitTimeMS must be a number

Error message

Argument for maxAwaitTimeMS must be a number

What it means

Thrown by FindCursor.maxAwaitTimeMS() (MongoInvalidArgumentError) when the value argument is not of type 'number'. maxAwaitTimeMS controls how long each getMore on a tailable awaitData cursor blocks waiting for new data; a non-numeric value (string from env, undefined, NaN from arithmetic) is rejected.

Source

Thrown at src/cursor/find_cursor.ts:342

   * Add a comment to the cursor query allowing for tracking the comment in the log.
   *
   * @param value - The comment attached to this query.
   */
  comment(value: string): this {
    this.throwIfInitialized();
    this.findOptions.comment = value;
    return this;
  }

  /**
   * Set a maxAwaitTimeMS on a tailing cursor query to allow to customize the timeout value for the option awaitData (Only supported on MongoDB 3.2 or higher, ignored otherwise)
   *
   * @param value - Number of milliseconds to wait before aborting the tailed query.
   */
  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;

View on GitHub (pinned to 3366c21a63)

Solutions

1. Coerce with Number() and validate: const ms = Number(val); if (Number.isFinite(ms)) cursor.maxAwaitTimeMS(ms)
2. Use a typed config loader (zod, envalid) that guarantees number output
3. Pass a numeric literal or constant

Example fix

// before
cursor.maxAwaitTimeMS(process.env.MAX_AWAIT_MS); // undefined
// after
const ms = Number(process.env.MAX_AWAIT_MS ?? 1000);
cursor.maxAwaitTimeMS(ms);

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

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

When it happens

Trigger: cursor.maxAwaitTimeMS('1000'), cursor.maxAwaitTimeMS(process.env.MAX_AWAIT) where the env var is unset/undefined, or cursor.maxAwaitTimeMS(NaN).

Common situations: Reading timeout values from environment variables or config without Number() coercion; passing a value through an any-typed helper that loses the type.

Related errors

• Argument for maxTimeMS 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/942eeb47b9f4fdf1.json. Report an issue: GitHub.