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

Remove hedge when constructing a primary read preference.

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

Solutions

Remove hedge when constructing a primary read preference.
Use secondaryPreferred/nearest if you want hedged reads.
Build options conditionally on the mode.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

function buildRP(mode, options) {
  if (mode === 'primary' && options?.hedge != null) {
    throw new Error('primary cannot have hedge');
  }
  return new ReadPreference(mode, undefined, options);
}

Type guard

function primaryHasHedge(mode, opts): boolean {
  return mode === 'primary' && opts?.hedge != null;
}

Try / catch

try {
  new ReadPreference(mode, undefined, opts);
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /hedge/.test(e.message)) {
    // drop hedge and retry
  }
  throw e;
}

Prevention

Apply hedge options only to non-primary modes.
Centralize read-preference construction.
Audit hedged-reads config for primary conflicts.

When it happens

Trigger: new ReadPreference('primary', undefined, { hedge: { enabled: true } }), or connection string mongodb://host/?readPreference=primary&hedgedReadsEnabled=true.

Common situations: Applying global hedge settings unconditionally, or templating read preference options without filtering for primary mode.

Related errors

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

Appendix: 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 dce7939f86)