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 when its argument is not of type 'number'. maxAwaitTimeMS controls how long the server blocks on a getMore for a tailable/awaitData cursor awaiting new data; the value must be a numeric millisecond count. A non-number (string, undefined after bad destructuring) is rejected synchronously.

Solutions

1. Coerce the value explicitly: cursor.maxAwaitTimeMS(Number(value)).
2. Guard with typeof before calling: if (typeof v === 'number') cursor.maxAwaitTimeMS(v).
3. Fix the config source so the value is a real number, not a string.

Example fix

// before
cursor.maxAwaitTimeMS(process.env.MAX_AWAIT_MS);

// after
cursor.maxAwaitTimeMS(Number(process.env.MAX_AWAIT_MS));

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

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

When it happens

Trigger: cursor.maxAwaitTimeMS('1000'); reading the value from config as a string and passing it uncoerced; cursor.maxAwaitTimeMS(someUndefinedVar); passing a value typed as number | undefined without a guard.

Common situations: Reading timeout values from environment variables (always strings) without Number(); JSON config files storing numbers as strings; optional config fields destructured with a default that resolves to undefined.

Related errors

• Argument for maxTimeMS must be a number
• Cannot specify maxAwaitTimeMS >= timeoutMS for a tailable…
• Operation "limit" requires an integer
• Operation "skip" requires an integer
• Tailable cursor does not support limit

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

Appendix: 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 dce7939f86)