mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Invalid read preference mode

Error message

Invalid read preference mode ${JSON.stringify(mode)}

What it means

Thrown by the ReadPreference constructor (src/read_preference.ts:86) when the mode is not one of the five valid values (primary, primaryPreferred, secondary, secondaryPreferred, nearest) or null. ReadPreference.isValid() builds a Set of the canonical modes; anything else raises MongoInvalidArgumentError with the JSON-stringified mode.

Solutions

1. Use one of the five lowercase canonical modes or a ReadPreference static instance (ReadPreference.secondary).
2. If reading from options, validate the value against the canonical set before constructing.
3. Use ReadPreference.fromString() only for trusted input; it does not validate the mode.

Example fix

// before
const rp = new ReadPreference('SECONDARY');
// after
const rp = new ReadPreference('secondary');
// or
const rp = ReadPreference.secondary;

const VALID_MODES = new Set(['primary','primaryPreferred','secondary','secondaryPreferred','nearest']);
function makeReadPreference(mode) {
  if (!VALID_MODES.has(mode)) throw new Error(`bad mode: ${mode}`);
  return new ReadPreference(mode);
}

function isReadPreferenceMode(m): m is 'primary'|'primaryPreferred'|'secondary'|'secondaryPreferred'|'nearest' {
  return typeof m === 'string' && ['primary','primaryPreferred','secondary','secondaryPreferred','nearest'].includes(m);
}

try {
  const rp = new ReadPreference(mode);
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /Invalid read preference mode/.test(e.message)) {
    // fall back to a safe default
  }
  throw e;
}

When it happens

Trigger: Constructing new ReadPreference('secondary-only'), new ReadPreference(2), new ReadPreference('SECONDARY') (case-sensitive), or passing a bad mode via options.readPreference on connect or per-operation options.

Common situations: Typos in read preference strings, case mismatches ('Primary' vs 'primary'), or passing a numeric/symbol from a different driver's convention.

Related errors

• Invalid read preference
• Invalid read preference specified
• maxStalenessSeconds must be a positive integer
• Primary read preference cannot be combined with hedge
• Primary read preference cannot be combined with…

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

Appendix: source

Thrown at src/read_preference.ts:86

  public static PRIMARY_PREFERRED = ReadPreferenceMode.primaryPreferred;
  public static SECONDARY = ReadPreferenceMode.secondary;
  public static SECONDARY_PREFERRED = ReadPreferenceMode.secondaryPreferred;
  public static NEAREST = ReadPreferenceMode.nearest;

  public static primary = new ReadPreference(ReadPreferenceMode.primary);
  public static primaryPreferred = new ReadPreference(ReadPreferenceMode.primaryPreferred);
  public static secondary = new ReadPreference(ReadPreferenceMode.secondary);
  public static secondaryPreferred = new ReadPreference(ReadPreferenceMode.secondaryPreferred);
  public static nearest = new ReadPreference(ReadPreferenceMode.nearest);

  /**
   * @param mode - A string describing the read preference mode (primary|primaryPreferred|secondary|secondaryPreferred|nearest)
   * @param tags - A tag set used to target reads to members with the specified tag(s). tagSet is not available if using read preference mode primary.
   * @param options - Additional read preference options
   */
  constructor(mode: ReadPreferenceMode, tags?: TagSet[], options?: ReadPreferenceOptions) {
    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');
      }

View on GitHub (pinned to dce7939f86)