mongodb/node-mongodb-native · error · MongoInvalidArgumentError

maxStalenessSeconds must be a positive integer

Error message

maxStalenessSeconds must be a positive integer

What it means

Thrown by the ReadPreference constructor (src/read_preference.ts:103) when options.maxStalenessSeconds is present but <= 0. The driver requires a positive integer for staleness-based secondary reads. Surfaces as MongoInvalidArgumentError.

Solutions

  1. Omit maxStalenessSeconds entirely if you do not want staleness limiting.
  2. Set it to a positive integer (minimum 90 seconds — see error 336).
  3. Validate config-supplied values before passing them to the driver.

Example fix

// before
const rp = new ReadPreference('secondary', undefined, { maxStalenessSeconds: 0 });
// after
const rp = new ReadPreference('secondary', undefined, { maxStalenessSeconds: 90 });
Defensive patterns

Strategy: validation

Validate before calling

function safeMaxStaleness(v) {
  if (v == null) return undefined;
  if (!Number.isInteger(v) || v <= 0) throw new Error('maxStalenessSeconds must be positive');
  return v;
}

Type guard

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

Try / catch

try {
  new ReadPreference('secondary', undefined, { maxStalenessSeconds });
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /positive integer/.test(e.message)) {
    // drop the option or set a valid value
  }
  throw e;
}

Prevention

When it happens

Trigger: Passing maxStalenessSeconds: 0, a negative number, or NaN (e.g. from a bad config parse) in ReadPreference options or via MongoClient URI ?maxStalenessSeconds=0.

Common situations: Treating 0 as 'disabled' (the driver treats 0 as invalid — omit the option instead), off-by-one in config, or unguarded user input.

Related errors

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

Appendix: source

Thrown at src/read_preference.ts:103

    if (!ReadPreference.isValid(mode)) {
      throw new MongoInvalidArgumentError(`Invalid read preference mode ${JSON.stringify(mode)}`);
    }
    if (options == null && typeof tags === 'object' && !Array.isArray(tags)) {
      options = tags;
      tags = undefined;
    } else if (tags && !Array.isArray(tags)) {
      throw new MongoInvalidArgumentError('ReadPreference tags must be an array');
    }

    this.mode = mode;
    this.tags = tags;
    this.hedge = options?.hedge;
    this.maxStalenessSeconds = undefined;

    options = options ?? {};
    if (options.maxStalenessSeconds != null) {
      if (options.maxStalenessSeconds <= 0) {
        throw new MongoInvalidArgumentError('maxStalenessSeconds must be a positive integer');
      }

      this.maxStalenessSeconds = options.maxStalenessSeconds;
    }

    if (this.mode === ReadPreference.PRIMARY) {
      if (this.tags && Array.isArray(this.tags) && this.tags.length > 0) {
        throw new MongoInvalidArgumentError('Primary read preference cannot be combined with tags');
      }

      if (this.maxStalenessSeconds) {
        throw new MongoInvalidArgumentError(
          'Primary read preference cannot be combined with maxStalenessSeconds'
        );
      }

      if (this.hedge) {
        throw new MongoInvalidArgumentError(

View on GitHub (pinned to dce7939f86)