mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Primary read preference cannot be combined with tags

Error message

Primary read preference cannot be combined with tags

What it means

Thrown by the ReadPreference constructor when mode is 'primary' AND a non-empty tags array is supplied. Tags target specific replica-set members for reads, but primary reads always go to the single primary - targeting tags with primary is contradictory and disallowed. MongoInvalidArgumentError. (An empty tags array is permitted; only a non-empty one triggers this.)

Source

Thrown at src/read_preference.ts:111

    }

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

  // Support the deprecated `preference` property introduced in the porcelain layer
  get preference(): ReadPreferenceMode {

View on GitHub (pinned to 3366c21a63)

Solutions

1. If you need primary reads, remove the tags.
2. If you need tag-targeted reads, switch the mode to primaryPreferred/secondary/secondaryPreferred/nearest.
3. Audit connection strings and option builders so tags and primary are not set together.
4. Use ReadPreference.primary (no tags) for unambiguous primary reads.

Example fix

// before
new ReadPreference('primary', [{ region: 'us-east' }]);
// after
ReadPreference.primary; // or
new ReadPreference('secondary', [{ region: 'us-east' }]);

if (mode === 'primary' && Array.isArray(tags) && tags.length > 0) {
  throw new Error('primary cannot be combined with tags');
}
new ReadPreference(mode, tags, options);

When it happens

Trigger: new ReadPreference('primary', [{ region: 'us-east' }]); passing readPreference=primary together with readPreferenceTags in a connection string; per-operation options that combine primary with tags via fromOptions/translate.

Common situations: Generic config templates that always set tags; switching a mode to primary without clearing tags; connection strings assembled from parts that independently set both.

Related errors

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

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