{"record":{"id":"d20b58ee164e81cb","repo":"mongodb/node-mongodb-native","slug":"primary-read-preference-cannot-be-combined-with-he","errorCode":null,"errorMessage":"Primary read preference cannot be combined with hedge","messagePattern":"Primary read preference cannot be combined with hedge","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/read_preference.ts","lineNumber":121,"sourceCode":"        throw new MongoInvalidArgumentError('maxStalenessSeconds must be a positive integer');\n      }\n\n      this.maxStalenessSeconds = options.maxStalenessSeconds;\n    }\n\n    if (this.mode === ReadPreference.PRIMARY) {\n      if (this.tags && Array.isArray(this.tags) && this.tags.length > 0) {\n        throw new MongoInvalidArgumentError('Primary read preference cannot be combined with tags');\n      }\n\n      if (this.maxStalenessSeconds) {\n        throw new MongoInvalidArgumentError(\n          'Primary read preference cannot be combined with maxStalenessSeconds'\n        );\n      }\n\n      if (this.hedge) {\n        throw new MongoInvalidArgumentError(\n          'Primary read preference cannot be combined with hedge'\n        );\n      }\n    }\n  }\n\n  // Support the deprecated `preference` property introduced in the porcelain layer\n  get preference(): ReadPreferenceMode {\n    return this.mode;\n  }\n\n  static fromString(mode: string): ReadPreference {\n    return new ReadPreference(mode as ReadPreferenceMode);\n  }\n\n  /**\n   * Construct a ReadPreference given an options object.\n   *","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/read_preference.ts#L103-L139","documentation":"Thrown by the ReadPreference constructor (src/read_preference.ts:121) when mode is 'primary' and hedge options are set. Hedged reads are a mechanism for distributing reads across multiple secondaries; they are not applicable to primary reads and the spec forbids the combination. MongoInvalidArgumentError.","triggerScenarios":"new ReadPreference('primary', undefined, { hedge: { enabled: true } }), or connection string mongodb://host/?readPreference=primary&hedgedReadsEnabled=true.","commonSituations":"Applying global hedge settings unconditionally, or templating read preference options without filtering for primary mode.","solutions":["Remove hedge when constructing a primary read preference.","Use secondaryPreferred/nearest if you want hedged reads.","Build options conditionally on the mode."],"exampleFix":"// before\nnew ReadPreference('primary', undefined, { hedge: { enabled: true } });\n// after\nnew ReadPreference('nearest', undefined, { hedge: { enabled: true } });","handlingStrategy":"validation","validationCode":"function buildRP(mode, options) {\n  if (mode === 'primary' && options?.hedge != null) {\n    throw new Error('primary cannot have hedge');\n  }\n  return new ReadPreference(mode, undefined, options);\n}","typeGuard":"function primaryHasHedge(mode, opts): boolean {\n  return mode === 'primary' && opts?.hedge != null;\n}","tryCatchPattern":"try {\n  new ReadPreference(mode, undefined, opts);\n} catch (e) {\n  if (e instanceof MongoInvalidArgumentError && /hedge/.test(e.message)) {\n    // drop hedge and retry\n  }\n  throw e;\n}","preventionTips":["Apply hedge options only to non-primary modes.","Centralize read-preference construction.","Audit hedged-reads config for primary conflicts."],"tags":["read-preference","validation","hedge","invalid-argument"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}