mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Primary read preference cannot be combined with…

Error message

Primary read preference cannot be combined with maxStalenessSeconds

What it means

Thrown by the ReadPreference constructor (src/read_preference.ts:115) when mode is 'primary' and options.maxStalenessSeconds is set. Staleness is only meaningful for secondary reads; the spec forbids combining it with primary. MongoInvalidArgumentError.

Solutions

Drop maxStalenessSeconds when using primary.
Switch to primaryPreferred or secondaryPreferred if staleness limiting is intended.
Conditionally build the options object based on mode.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

function buildRP(mode, options) {
  if (mode === 'primary' && options?.maxStalenessSeconds != null) {
    throw new Error('primary cannot have maxStalenessSeconds');
  }
  return new ReadPreference(mode, undefined, options);
}

Type guard

function primaryHasMaxStaleness(mode, opts): boolean {
  return mode === 'primary' && opts?.maxStalenessSeconds != null;
}

Try / catch

try {
  new ReadPreference(mode, undefined, opts);
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /maxStalenessSeconds/.test(e.message)) {
    // remove staleness option and retry
  }
  throw e;
}

Prevention

Do not apply global maxStalenessSeconds across all modes.
Validate option/mode combinations in a shared builder.
Review templated connection strings for this conflict.

When it happens

Trigger: new ReadPreference('primary', undefined, { maxStalenessSeconds: 90 }), or connection string mongodb://host/?readPreference=primary&maxStalenessSeconds=90.

Common situations: Inheriting a global maxStalenessSeconds config across all read preference modes, or templated connection strings.

Related errors

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

Appendix: source

Thrown at src/read_preference.ts:115

    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(
          'Primary read preference cannot be combined with hedge'
        );
      }
    }
  }

  // Support the deprecated `preference` property introduced in the porcelain layer
  get preference(): ReadPreferenceMode {
    return this.mode;
  }

  static fromString(mode: string): ReadPreference {

View on GitHub (pinned to dce7939f86)