mongodb/node-mongodb-native · error · MongoParseError

Unknown ReadPreference value

Error message

Unknown ReadPreference value: ${value}

What it means

The `readPreference` transform at src/connection_string.ts:1010 handles three shapes: a ReadPreference instance, a record with a `mode` field, or a plain string. Anything else falls through to the final throw at src/connection_string.ts:1036 (`Unknown ReadPreference value`).

Solutions

1. Pass a string mode: `readPreference: 'secondary'`.
2. Or an object with a mode: `readPreference: { mode: 'secondary' }`.
3. Move tag sets to the dedicated `readPreferenceTags` option.

Example fix

// before
new MongoClient(uri, { readPreference: 2 });

// after
new MongoClient(uri, { readPreference: 'secondary' });

import { ReadPreference } from 'mongodb';
function isReadPreferenceInput(v: unknown): boolean {
  return v instanceof ReadPreference || typeof v === 'string' || (!!v && typeof v === 'object' && 'mode' in v);
}
if (opts.readPreference != null && !isReadPreferenceInput(opts.readPreference)) {
  throw new Error('readPreference must be a string, { mode }, or ReadPreference instance');
}

function isReadPreferenceInput(v: unknown): v is string | { mode: string } { return typeof v === 'string' || (!!v && typeof v === 'object' && 'mode' in v); }

try { client = new MongoClient(uri, opts); } catch (e) { if (e instanceof MongoParseError && /Unknown ReadPreference/.test(e.message)) { opts.readPreference = 'primary'; client = new MongoClient(uri, opts); } else throw e; }

When it happens

Trigger: Passing `readPreference: 2`, `readPreference: true`, `readPreference: ['secondary']`, `readPreference: null`, or a tags-only object with no `mode` key.

Common situations: Passing a numeric priority (confusing with read preference integers in some clients); reusing a config field typed as `string | number`; passing a tags array directly under readPreference instead of `readPreferenceTags`.

Related errors

• Cannot make read preference from
• compressors must be an array or a comma-delimited list of…
• Invalid WriteConcern cannot parse
• Option 'mongodbLogComponentSeverities' must be a non-null…
• Option 'mongodbLogPath' must be of type 'stderr' | 'stdout'…

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

Appendix: source

Thrown at src/connection_string.ts:1036

        const rp = ReadPreference.fromOptions({
          readPreference: { ...options.readPreference, ...value },
          ...value
        });
        if (rp) return rp;
        else throw new MongoParseError(`Cannot make read preference from ${JSON.stringify(value)}`);
      }
      if (typeof value === 'string') {
        const rpOpts = {
          hedge: options.readPreference?.hedge,
          maxStalenessSeconds: options.readPreference?.maxStalenessSeconds
        };
        return new ReadPreference(
          value as ReadPreferenceMode,
          options.readPreference?.tags,
          rpOpts
        );
      }
      throw new MongoParseError(`Unknown ReadPreference value: ${value}`);
    }
  },
  readPreferenceTags: {
    target: 'readPreference',
    transform({
      values,
      options
    }: {
      values: Array<string | Record<string, string>[]>;
      options: MongoClientOptions;
    }) {
      const tags: Array<string | Record<string, string>> = Array.isArray(values[0])
        ? values[0]
        : (values as Array<string>);
      const readPreferenceTags = [];
      for (const tag of tags) {
        const readPreferenceTag: TagSet = Object.create(null);
        if (typeof tag === 'string') {

View on GitHub (pinned to dce7939f86)