mongodb/node-mongodb-native · error · MongoInvalidArgumentError

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

Error message

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

What it means

Thrown by the ReadPreference constructor when the mode is not one of 'primary', 'primaryPreferred', 'secondary', 'secondaryPreferred', 'nearest' (or null). ReadPreference.isValid rejects any other string/value. MongoInvalidArgumentError, raised wherever a ReadPreference is constructed - directly, via fromOptions, fromString, or translate (e.g., parsing a readPreference from connection options or per-operation options).

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

Solutions

1. Use one of the documented modes: primary, primaryPreferred, secondary, secondaryPreferred, nearest.
2. Use the ReadPreference static instances (ReadPreference.secondary) or ReadPreferenceMode constants to avoid typos.
3. Validate user/config-supplied mode strings against the allowed set before constructing a ReadPreference.
4. Check connection-string readPreference tokens for typos.

Example fix

// before
new ReadPreference('secondry');
// after
new ReadPreference('secondary');
// or
ReadPreference.secondary;

import { ReadPreferenceMode } from 'mongodb';
const validModes = new Set<string>(Object.values(ReadPreferenceMode));
if (!validModes.has(mode)) throw new Error(`readPreference mode invalid: ${mode}`);
const rp = new ReadPreference(mode as any);

import { ReadPreferenceMode } from 'mongodb';
function isReadPreferenceMode(v: unknown): v is (typeof ReadPreferenceMode)[keyof typeof ReadPreferenceMode] {
  return typeof v === 'string' && Object.values(ReadPreferenceMode).includes(v as any);
}

When it happens

Trigger: Passing a typo'd or unsupported mode string such as 'secondry', 'prefer-secondary', 'nearestRead', or a numeric/boolean value; setting readPreference in the URI or options to an invalid token; constructing new ReadPreference('random').

Common situations: Bad URI query param (?readPreference=...); environment-variable-driven config with a typo; code computing a mode string from user input without validation; mixing camelCase ('secondaryPreferred') vs different separators.

Related errors

• ReadPreference tags must be an array
• maxStalenessSeconds must be a positive integer
• Primary read preference cannot be combined with tags
• Primary read preference cannot be combined with maxStaleness
• Update document requires atomic operators

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