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 when options.maxStalenessSeconds is provided and is <= 0. Max staleness governs how stale a secondary can be for reads; it must be a positive integer (and per the server spec, effectively >= 90 seconds - the server enforces the 90s floor separately). The driver rejects non-positive values client-side. MongoInvalidArgumentError.

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

Solutions

1. Set maxStalenessSeconds to a positive integer (>= 90 to satisfy the server-side minimum).
2. Omit maxStalenessSeconds entirely if you don't want a staleness constraint.
3. Validate that computed values are positive integers before passing them in.
4. Double-check units - the field is seconds, not milliseconds.

Example fix

// before
new ReadPreference('secondary', undefined, { maxStalenessSeconds: 0 });
// after
new ReadPreference('secondary', undefined, { maxStalenessSeconds: 90 });

if (maxStalenessSeconds != null && !(Number.isInteger(maxStalenessSeconds) && maxStalenessSeconds > 0)) {
  throw new Error('maxStalenessSeconds must be a positive integer (>=90)');
}
new ReadPreference(mode, tags, { maxStalenessSeconds });

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

When it happens

Trigger: Passing maxStalenessSeconds: 0 or a negative number; passing a value computed from arithmetic that underflows to 0/negative; passing a non-numeric that survives the null check but is <= 0 in comparison coercion.

Common situations: Config defaults of 0 meaning 'disabled' but interpreted literally; off-by-one or rounding producing 0; copying a value meant as milliseconds into a seconds field.

Related errors

• Primary read preference cannot be combined with maxStaleness
• Invalid read preference mode ${JSON.stringify(mode)}
• ReadPreference tags must be an array
• Primary read preference cannot be combined with tags
• Update document requires atomic operators

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