What causes "Primary read preference cannot be combined with hedge" in mongodb/node-mongodb-native?

Remove the `hedge` option wherever `readPreference` is 'primary' (or default, which resolves to primary).

mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Primary read preference cannot be combined with hedge

Error message

Primary read preference cannot be combined with hedge

What it means

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).

Source

Thrown at src/read_preference.ts:121

        throw new MongoInvalidArgumentError('maxStalenessSeconds must be a positive integer');
      }

      this.maxStalenessSeconds = options.maxStalenessSeconds;
    }

    if (this.mode === ReadPreference.PRIMARY) {
      if (this.tags && Array.isArray(this.tags) && this.tags.length > 0) {
        throw new MongoInvalidArgumentError('Primary read preference cannot be combined with tags');
      }

      if (this.maxStalenessSeconds) {
        throw new MongoInvalidArgumentError(
          'Primary read preference cannot be combined with maxStalenessSeconds'
        );
      }

      if (this.hedge) {
        throw new MongoInvalidArgumentError(
          'Primary read preference cannot be combined with hedge'
        );
      }
    }
  }

  // Support the deprecated `preference` property introduced in the porcelain layer
  get preference(): ReadPreferenceMode {
    return this.mode;
  }

  static fromString(mode: string): ReadPreference {
    return new ReadPreference(mode as ReadPreferenceMode);
  }

  /**
   * Construct a ReadPreference given an options object.
   *

View on GitHub (pinned to 3366c21a63)

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.

Example fix

// before
new ReadPreference('primary', null, { hedge: { enabled: true } });
// after
new ReadPreference('nearest', null, { hedge: { enabled: true } });

Defensive patterns

Strategy: validation

Validate before calling

function makeReadPref(mode, opts = {}) {
  if (mode === 'primary' && opts.hedge) {
    throw new TypeError('hedge is invalid for primary read preference');
  }
  return new ReadPreference(mode, null, opts);
}

Type guard

function isHedgeCompatible(mode) {
  return mode !== 'primary';
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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