{"record":{"id":"5d07c1ee42e8c83c","repo":"mongodb/node-mongodb-native","slug":"invalid-read-preference-readpreference","errorCode":null,"errorMessage":"Invalid read preference: ${readPreference}","messagePattern":"Invalid read preference: (.+?)","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/cursor/abstract_cursor.ts","lineNumber":760,"sourceCode":"      this.transform = transform;\n    }\n\n    return this as unknown as AbstractCursor<T>;\n  }\n\n  /**\n   * Set the ReadPreference for the cursor.\n   *\n   * @param readPreference - The new read preference for the cursor.\n   */\n  withReadPreference(readPreference: ReadPreferenceLike): this {\n    this.throwIfInitialized();\n    if (readPreference instanceof ReadPreference) {\n      this.cursorOptions.readPreference = readPreference;\n    } else if (typeof readPreference === 'string') {\n      this.cursorOptions.readPreference = ReadPreference.fromString(readPreference);\n    } else {\n      throw new MongoInvalidArgumentError(`Invalid read preference: ${readPreference}`);\n    }\n\n    return this;\n  }\n\n  /**\n   * Set the ReadPreference for the cursor.\n   *\n   * @param readPreference - The new read preference for the cursor.\n   */\n  withReadConcern(readConcern: ReadConcernLike): this {\n    this.throwIfInitialized();\n    const resolvedReadConcern = ReadConcern.fromOptions({ readConcern });\n    if (resolvedReadConcern) {\n      this.cursorOptions.readConcern = resolvedReadConcern;\n    }\n\n    return this;","sourceCodeStart":742,"sourceCodeEnd":778,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/cursor/abstract_cursor.ts#L742-L778","documentation":"Thrown as a MongoInvalidArgumentError from withReadPreference() when the argument is neither a ReadPreference instance nor a string. The method accepts those two shapes (a string is parsed via ReadPreference.fromString) and rejects everything else (numbers, plain objects without the mode, null) so an invalid preference does not silently fall back to primary. It runs after throwIfInitialized(), so it also cannot be changed once iteration has started.","triggerScenarios":"cursor.withReadPreference({ mode: 'nearest' }) (plain object instead of ReadPreference instance); cursor.withReadPreference(2); cursor.withReadPreference(null).","commonSituations":"Passing a raw options object shaped like a read preference; deserializing a preference from JSON into a plain object; confusing the readPreference string ('secondary') with a numeric enum from another driver.","solutions":["Pass a string mode: cursor.withReadPreference('secondary').","Or pass a ReadPreference instance: cursor.withReadPreference(new ReadPreference('nearest')).","Set readPreference in the cursor options object at construction time using a recognized string/instance."],"exampleFix":"// before: plain object is not accepted\ncursor.withReadPreference({ mode: 'nearest' });\n\n// after: use a string or a ReadPreference instance\ncursor.withReadPreference('nearest');\n// or\ncursor.withReadPreference(new ReadPreference('nearest', [{ tag: 'region', value: 'eu' }]));","handlingStrategy":"type-guard","validationCode":"import { ReadPreference } from 'mongodb';\nif (typeof rp !== 'string' && !(rp instanceof ReadPreference)) {\n  throw new TypeError('readPreference must be a string or ReadPreference instance');\n}","typeGuard":"import { ReadPreference, type ReadPreferenceLike } from 'mongodb';\nfunction isReadPreferenceLike(v: unknown): v is ReadPreferenceLike {\n  return typeof v === 'string' || v instanceof ReadPreference;\n}","tryCatchPattern":null,"preventionTips":["Pass a string mode ('primary','primaryPreferred','secondary','secondaryPreferred','nearest') or a ReadPreference instance.","Do not pass plain { mode: '...' } objects.","Set readPreference in the cursor options object when possible."],"tags":["cursor","read-preference","invalid-argument","typescript"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}