mongodb/node-mongodb-native · error · MongoParseError

Cannot combine replicaSet option with srvMaxHosts

Error message

Cannot combine replicaSet option with srvMaxHosts

What it means

Thrown by resolveSRVRecord() when, for a mongodb+srv:// URI, both the replicaSet option is set and srvMaxHosts is greater than 0. srvMaxHosts limits the number of hosts selected from the SRV result, which is incompatible with replicaSet semantics (the driver must know all members). This is a MongoParseError raised during SRV resolution.

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 3366c21a63)

Solutions

1. Drop srvMaxHosts from the URI/options when connecting to a replica set.
2. Drop replicaSet from the URI (and TXT record) when using srvMaxHosts against a load-balanced/sharded front.
3. Re-check the TXT record does not inject replicaSet while you set srvMaxHosts client-side.
4. Validate the resolved options by logging them before connect in non-production.

Example fix

// before
mongodb+srv://cluster.example.net/db?replicaSet=rs0&srvMaxHosts=3
// after (replica set)
mongodb+srv://cluster.example.net/db?replicaSet=rs0
// after (sharded, srvMaxHosts)
mongodb+srv://cluster.example.net/db?srvMaxHosts=3&loadBalanced=true

function validateSrvOptions(opts: { replicaSet?: string; srvMaxHosts?: number }): void {
  if (opts.replicaSet && (opts.srvMaxHosts ?? 0) > 0) {
    throw new Error('Cannot combine replicaSet with srvMaxHosts > 0');
  }
}
validateSrvOptions({ replicaSet: process.env.REPLICA_SET, srvMaxHosts: Number(process.env.SRV_MAX_HOSTS ?? 0) });

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoParseError && /Cannot combine replicaSet option with srvMaxHosts/.test(e.message)) {
    // drop one of the two and retry, or alert ops
  }
  throw e;
}

When it happens

Trigger: URI like mongodb+srv://host/db?replicaSet=rs0&srvMaxHosts=3; passing srvMaxHosts via the options object while replicaSet is in the URI (or TXT record); load-balanced or sharded setups where srvMaxHosts was copied from a template that also sets replicaSet.

Common situations: Copying an Atlas URI template that includes replicaSet then adding srvMaxHosts to limit hosts; mixing TXT-provided replicaSet with a client option srvMaxHosts; misunderstanding that srvMaxHosts is for sharded clusters without replicaSet.

Related errors

• Option "srvHost" must not be empty
• Multiple text records not allowed
• Text record may only set any of: ${VALID_TXT_RECORDS.join(',
• Cannot have empty URI params in DNS TXT Record
• Cannot use srvMaxHosts option with replicaSet

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