mongodb/node-mongodb-native · error · MongoParseError

Cannot make read preference from

Error message

Cannot make read preference from ${JSON.stringify(value)}

What it means

When `readPreference` is an object, the transform at src/connection_string.ts:1017 first requires it to be a record with a `mode` field, then calls `ReadPreference.fromOptions`; if fromOptions returns null, MongoParseError is thrown at src/connection_string.ts:1023. This typically means the `mode` value is not a recognized ReadPreferenceMode.

Solutions

1. Use a valid mode: primary, primaryPreferred, secondary, secondaryPreferred, or nearest.
2. Pass a plain string: `readPreference: 'secondary'` instead of an object when no tags/hedge are needed.
3. Confirm the merged object still has a `mode` field after any config spread.

Example fix

// before
new MongoClient(uri, { readPreference: { mode: 'primary-only' } });

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

const MODES = ['primary','primaryPreferred','secondary','secondaryPreferred','nearest'];
if (opts.readPreference && typeof opts.readPreference === 'object' && 'mode' in opts.readPreference) {
  if (!MODES.includes((opts.readPreference as any).mode)) {
    throw new Error(`invalid readPreference mode: ${(opts.readPreference as any).mode}`);
  }
}

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

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

When it happens

Trigger: Passing `readPreference: { mode: 'primary-only' }`, `{ mode: 'standalone' }`, `{ mode: 'PRIMARY' }` (case mismatch), or any mode that is not one of primary, primaryPreferred, secondary, secondaryPreferred, nearest.

Common situations: Case-sensitivity mistakes (uppercase from another SDK); invented mode names; copying tags-only objects without a valid mode; merging configs that leave mode undefined inside the spread.

Related errors

• Option "readPreference" must be a ReadPreference instance
• Unknown ReadPreference value
• Auth mechanism property ALLOWED_HOSTS must be an array of…
• AuthContext must provide credentials.
• AuthContext must provide credentials.

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

Appendix: source

Thrown at src/connection_string.ts:1023

      });
    }
  },
  readPreference: {
    default: ReadPreference.primary,
    transform({ values: [value], options }) {
      if (value instanceof ReadPreference) {
        return ReadPreference.fromOptions({
          readPreference: { ...options.readPreference, ...value },
          ...value
        });
      }
      if (isRecord(value, ['mode'] as const)) {
        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({

View on GitHub (pinned to dce7939f86)