mongodb/node-mongodb-native · error · MongoParseError

Cannot combine replicaSet option with srvMaxHosts

Error message

Cannot combine replicaSet option with srvMaxHosts

What it means

srvMaxHosts caps the number of hosts the driver selects from the SRV result, while replicaSet directs the driver to discover members via the replica set itself. The two options contradict each other (manual host limit vs. topology-driven discovery), so the SRV spec forbids combining them. This check runs after TXT options are merged into options.

Solutions

1. Remove the replicaSet option if you want srvMaxHosts to limit SRV hosts.
2. Or set srvMaxHosts to 0 (or omit it) if you need replicaSet-based discovery.

Example fix

// before
new MongoClient('mongodb+srv://host/db?replicaSet=rs0&srvMaxHosts=3');
// after
new MongoClient('mongodb+srv://host/db?srvMaxHosts=3');

function assertNoReplicaSetWithSrvMaxHosts(opts: Record<string, unknown>) {
  if (opts.replicaSet != null && Number(opts.srvMaxHosts) > 0) {
    throw new Error('Cannot combine replicaSet with srvMaxHosts > 0');
  }
}

When it happens

Trigger: A mongodb+srv:// URI or client config where both replicaSet is set (URI, TXT, or options) AND srvMaxHosts is greater than zero.

Common situations: Copy-pasting a replicaSet query param while adding srvMaxHosts to limit hosts in a sharded/load-balanced setup, or inheriting replicaSet from a TXT record and then setting srvMaxHosts in code.

Related errors

• Cannot have empty URI params in DNS TXT Record
• Cannot use srvMaxHosts option with replicaSet
• Text record may only set any of
• All values of tls/ssl must be the same.
• Auth mechanism property ALLOWED_HOSTS is not allowed in the…

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

Appendix: source

Thrown at src/connection_string.ts:152

  if (
    !options.userSpecifiedAuthSource &&
    source &&
    options.credentials &&
    !AUTH_MECHS_AUTH_SRC_EXTERNAL.has(options.credentials.mechanism)
  ) {
    options.credentials = MongoCredentials.merge(options.credentials, { source });
  }

  if (!options.userSpecifiedReplicaSet && replicaSet) {
    options.replicaSet = replicaSet;
  }

  if (loadBalanced === 'true') {
    options.loadBalanced = true;
  }

  if (options.replicaSet && options.srvMaxHosts > 0) {
    throw new MongoParseError('Cannot combine replicaSet option with srvMaxHosts');
  }

  validateLoadBalancedOptions(hostAddresses, options, true);

  return hostAddresses;
}

/**
 * Checks if TLS options are valid
 *
 * @param allOptions - All options provided by user or included in default options map
 * @throws MongoAPIError if TLS options are invalid
 */
function checkTLSOptions(allOptions: CaseInsensitiveMap): void {
  if (!allOptions) return;
  const check = (a: string, b: string) => {
    if (allOptions.has(a) && allOptions.has(b)) {
      throw new MongoAPIError(`The '${a}' option cannot be used with the '${b}' option`);

View on GitHub (pinned to dce7939f86)