mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Operation "batchSize" requires an integer

Error message

Operation "batchSize" requires an integer

What it means

Thrown by cursor.batchSize(value) when value is not of type 'number' (on a non-tailable cursor). The driver requires a numeric integer for batchSize; strings, undefined, and BigInt are rejected. Note the message says 'requires an integer' but the runtime check is only typeof === 'number' — non-integer numbers are not caught here (the server may reject them).

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

Solutions

1. Coerce: batchSize(Number(value)).
2. Ensure integer-ness with Math.floor or guard: if (!Number.isInteger(v)) throw.
3. Type the option as number in your config schema.

Example fix

// before
cursor.batchSize(config.batch); // string from env
// after
cursor.batchSize(Number(config.batch));

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

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

When it happens

Trigger: Calling batchSize('100'), batchSize(process.env.BATCH) with a string env var, batchSize(BigInt(100)), or batchSize(undefined). Fractional numbers like 1.5 pass the check but are invalid downstream.

Common situations: Env-var or JSON config feeding a string; missing value defaulting to undefined; copying a value that was typed loosely elsewhere.

Related errors

• Flag ${flag} must be a boolean value
• Invalid read preference: ${readPreference}
• Argument for maxTimeMS must be a number
• Cursor options must be an object
• User input for option 'mongodbLogComponentSeverities' object

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