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 (src/read_preference.ts:111) when mode is 'primary' and a non-empty tags array is supplied. Per the MongoDB read preference specification, primary reads always target the primary, so tag-based routing is meaningless and explicitly forbidden. MongoInvalidArgumentError.

Solutions

1. Remove tags when using primary mode.
2. Use primaryPreferred if you want primary-first with tag fallback.
3. Audit connection strings and option builders to drop tags for primary.

Example fix

// before
new ReadPreference('primary', [{ region: 'us' }]);
// after
new ReadPreference('primary');

function buildRP(mode, tags) {
  if (mode === 'primary' && tags != null && tags.length > 0) {
    throw new Error('primary cannot have tags');
  }
  return new ReadPreference(mode, tags);
}

function primaryHasTags(mode, tags): boolean {
  return mode === 'primary' && Array.isArray(tags) && tags.length > 0;
}

try {
  new ReadPreference(mode, tags);
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /cannot be combined with tags/.test(e.message)) {
    // strip tags and retry
  }
  throw e;
}

When it happens

Trigger: new ReadPreference('primary', [{ region: 'us' }]), or a connection string like mongodb://host/?readPreference=primary&readPreferenceTags=region:us, or per-operation options combining primary with tags.

Common situations: Applying a global tag configuration unconditionally across all read preferences, including primary; copy-pasted connection strings.

Related errors

• ReadPreference tags must be an array
• Invalid read preference mode
• Invalid read preference
• Invalid read preference specified
• maxStalenessSeconds must be a positive integer

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

Appendix: 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 dce7939f86)