mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Operation "batchSize" requires an integer

Error message

Operation "batchSize" requires an integer

What it means

Thrown as a MongoInvalidArgumentError from batchSize() when the value argument fails `typeof value !== 'number'`. The message says 'requires an integer' but the implementation only checks for the number type at this line (it does not verify the value is an integer); batchSize is encoded as an int32 on the wire, so a non-number cannot be sent. The check runs after the tailable guard and only when the cursor is not initialized.

Solutions

1. Pass a number, preferably an integer: cursor.batchSize(100).
2. Parse config strings: cursor.batchSize(Number(process.env.BATCH_SIZE)).
3. If you rely on integer validation, add your own Number.isInteger(value) check before calling batchSize(), since the driver only checks the type here.

Example fix

// before: string value
const size = process.env.BATCH_SIZE; // '100'
cursor.batchSize(size);

// after: parse and (optionally) validate integer
cursor.batchSize(Number(process.env.BATCH_SIZE));

if (typeof value !== 'number' || !Number.isInteger(value)) {
  throw new TypeError('batchSize must be an integer');
}
cursor.batchSize(value);

function isInteger(v: unknown): v is number {
  return typeof v === 'number' && Number.isInteger(v);
}

When it happens

Trigger: cursor.batchSize('100'); cursor.batchSize(undefined); cursor.batchSize(100.5) passes the type check but is not actually an integer (the message is slightly stricter than the code).

Common situations: Passing a batchSize from JSON/env as a string; sharing an options object where batchSize was conditionally deleted to undefined; reading the error message and assuming integer validation that the code does not perform.

Related errors

• Argument for maxTimeMS must be a number
• Argument "iterator" must be a function
• Flag is not one of
• Flag must be a boolean value
• Invalid read preference

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

Appendix: source

Thrown at src/cursor/abstract_cursor.ts:808

    }

    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') {
      throw new MongoInvalidArgumentError('Operation "batchSize" requires an integer');
    }

    this.cursorOptions.batchSize = value;
    return this;
  }

  /**
   * Rewind this cursor to its uninitialized state. Any options that are present on the cursor will
   * remain in effect. Iterating this cursor will cause new queries to be sent to the server, even
   * if the resultant data has already been retrieved by this cursor.
   */
  rewind(): void {
    if (this.timeoutContext && this.timeoutContext.owner !== this) {
      throw new MongoAPIError(`Cannot rewind cursor that does not own its timeout context.`);
    }
    if (!this.initialized) {
      return;
    }

View on GitHub (pinned to dce7939f86)