mongodb/node-mongodb-native · error · MongoParseError

Unknown ReadPreference value: ${value}

Error message

Unknown ReadPreference value: ${value}

What it means

`readPreference` must be a `ReadPreference` instance, an object with a `mode` key, or a string. If it is none of these (number, boolean, array, null), the transform throws 'Unknown ReadPreference value' at src/connection_string.ts:1036.

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

Solutions

1. Set readPreference to a string mode like 'secondary'
2. Or an object `{ mode: 'secondary' }`
3. Or a ReadPreference instance
4. Omit the option to default to 'primary'

Example fix

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

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

import { ReadPreference } from 'mongodb';
function isReadPreferenceLike(v) {
  return v instanceof ReadPreference || typeof v === 'string' || (!!v && typeof v === 'object' && 'mode' in v);
}

When it happens

Trigger: `{ readPreference: 2 }`; `{ readPreference: true }`; `{ readPreference: null }`; `{ readPreference: ['secondary'] }`.

Common situations: Config typos; passing a numeric priority; passing null intentionally but hitting the type check; array from a parsed query string.

Related errors

• Cannot make read preference from ${JSON.stringify(value)}
• Option "readPreference" must be a ReadPreference instance
• Descriptors missing a type must define a transform
• ${name} must be an object with 'username' and 'password' pro
• authMechanism one of ${mechanisms}, got ${value}

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