mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Primary read preference cannot be combined with maxStaleness

Error message

Primary read preference cannot be combined with maxStalenessSeconds

What it means

Thrown by the ReadPreference constructor when mode is 'primary' AND options.maxStalenessSeconds is set (truthy). Max staleness only makes sense for reads that can go to secondaries; the primary has no staleness concept, so combining them is contradictory and rejected. MongoInvalidArgumentError.

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

Solutions

1. Drop maxStalenessSeconds when using primary reads.
2. If you want staleness-bounded reads, use a non-primary mode (primaryPreferred/secondary/secondaryPreferred/nearest).
3. Separate the primary and secondary read-preference configs so the staleness option isn't carried into primary.
4. Validate option combinations before constructing a ReadPreference.

Example fix

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

if (mode === 'primary' && options?.maxStalenessSeconds) {
  throw new Error('primary cannot be combined with maxStalenessSeconds');
}
new ReadPreference(mode, tags, options);

When it happens

Trigger: new ReadPreference('primary', undefined, { maxStalenessSeconds: 90 }); connection strings with both readPreference=primary and maxStalenessSeconds; per-operation options that set both via fromOptions/translate; generic option objects reused across modes.

Common situations: Shared read-preference option objects reused for both primary and secondary paths; config that sets maxStalenessSeconds globally and then a specific call forces primary; connection-string builders that concatenate independent settings.

Related errors

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

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