mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Invalid read preference

Error message

Invalid read preference: ${r}

What it means

Thrown by ReadPreference.translate() (src/read_preference.ts:191) when options.readPreference is not a string, not a plain object, and not a ReadPreference instance. translate() converts a loosely-typed read preference value into a ReadPreference; any other type (number, array, boolean, null after the earlier null check) is rejected. MongoInvalidArgumentError.

Solutions

1. Pass readPreference as a string ('secondary'), an object ({ mode: 'secondary' }), or a ReadPreference instance.
2. Normalize config values before they reach the driver.
3. Use ReadPreference.fromOptions() which is more lenient with object shapes.

Example fix

// before
ReadPreference.translate({ readPreference: 2 });
// after
ReadPreference.translate({ readPreference: 'secondary' });

function normalizeRP(v) {
  if (typeof v === 'string') return new ReadPreference(v);
  if (v && typeof v === 'object' && typeof v.mode === 'string') return new ReadPreference(v.mode, v.tags, { maxStalenessSeconds: v.maxStalenessSeconds });
  throw new Error('readPreference must be string, object, or ReadPreference');
}

function isReadPreferenceLike(v): v is string | { mode: string } | ReadPreference {
  return typeof v === 'string' || (v != null && typeof v === 'object' && ('mode' in v || v instanceof ReadPreference));
}

try {
  ReadPreference.translate({ readPreference: rp });
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /Invalid read preference/.test(e.message)) {
    // replace with a valid value
  }
  throw e;
}

When it happens

Trigger: Passing options.readPreference = 2, options.readPreference = ['secondary'], options.readPreference = true, or a value of an unexpected type through translate().

Common situations: Deserialization from a config format that produced a non-string/non-object value, or a programming error passing the wrong variable.

Related errors

• Invalid read preference mode
• 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/8d9e28e6992453d4. Report an issue: GitHub.

Appendix: source

Thrown at src/read_preference.ts:191

  /**
   * Replaces options.readPreference with a ReadPreference instance
   */
  static translate(options: ReadPreferenceLikeOptions): ReadPreferenceLikeOptions {
    if (options.readPreference == null) return options;
    const r = options.readPreference;

    if (typeof r === 'string') {
      options.readPreference = new ReadPreference(r);
    } else if (r && !(r instanceof ReadPreference) && typeof r === 'object') {
      const mode = r.mode || r.preference;
      if (mode && typeof mode === 'string') {
        options.readPreference = new ReadPreference(mode, r.tags, {
          maxStalenessSeconds: r.maxStalenessSeconds
        });
      }
    } else if (!(r instanceof ReadPreference)) {
      throw new MongoInvalidArgumentError(`Invalid read preference: ${r}`);
    }

    return options;
  }

  /**
   * Validate if a mode is legal
   *
   * @param mode - The string representing the read preference mode.
   */
  static isValid(mode: string): boolean {
    const VALID_MODES = new Set([
      ReadPreference.PRIMARY,
      ReadPreference.PRIMARY_PREFERRED,
      ReadPreference.SECONDARY,
      ReadPreference.SECONDARY_PREFERRED,
      ReadPreference.NEAREST,
      null

View on GitHub (pinned to dce7939f86)