{"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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/read_preference.ts#L103-L139","documentation":"Thrown by the ReadPreference constructor when mode is 'primary' and the hedge option is also set. Hedged reads dispatch the same query to multiple secondaries and return the fastest response, which is meaningless for a primary-only read, so MongoDB forbids the combination. The driver enforces this client-side at construction time (read_preference.ts:120).","triggerScenarios":"Calling `new ReadPreference('primary', null, { hedge: { enabled: true } })`, or passing `{ readPreference: 'primary', hedge: { enabled: true } }` to a Collection/Db/Cursor, or setting hedge globally on the MongoClient and then forcing a primary read.","commonSituations":"Global hedge config copied into a connection string while a specific operation overrides readPreference to 'primary'; mixing a replica-set-wide hedge setting with primary reads; misreading docs and assuming hedge applies to all modes.","solutions":["Remove the `hedge` option wherever `readPreference` is 'primary' (or default, which resolves to primary).","If you need hedged reads, switch the read preference to 'secondary', 'secondaryPreferred', or 'nearest'.","Scope hedge to non-primary read preferences only, e.g. set it per-call rather than on the client."],"exampleFix":"// before\nnew ReadPreference('primary', null, { hedge: { enabled: true } });\n// after\nnew ReadPreference('nearest', null, { hedge: { enabled: true } });","handlingStrategy":"validation","validationCode":"function makeReadPref(mode, opts = {}) {\n  if (mode === 'primary' && opts.hedge) {\n    throw new TypeError('hedge is invalid for primary read preference');\n  }\n  return new ReadPreference(mode, null, opts);\n}","typeGuard":"function isHedgeCompatible(mode) {\n  return mode !== 'primary';\n}","tryCatchPattern":null,"preventionTips":["Centralize read-preference construction in one helper that rejects primary+hedge.","Set hedge per-operation, not globally, so it never silently combines with primary.","Add a unit test asserting primary + hedge throws early."],"tags":["read-preference","configuration","validation"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}