mongodb/node-mongodb-native · error · MongoParseError

Cannot use srvMaxHosts option with replicaSet

Error message

Cannot use srvMaxHosts option with replicaSet

What it means

Thrown when an SRV URI is used, srvMaxHosts is greater than 0, and a replicaSet name is also specified (connection_string.ts:476-478). srvMaxHosts randomly limits the hosts returned by SRV to introduce randomization, but pinning a replicaSet name requires connecting to all members for election-aware routing; the two are mutually exclusive.

Source

Thrown at src/connection_string.ts:477

  }

  // Potential SRV Overrides and SRV connection string validations

  mongoOptions.userSpecifiedAuthSource =
    objectOptions.has('authSource') || urlOptions.has('authSource');
  mongoOptions.userSpecifiedReplicaSet =
    objectOptions.has('replicaSet') || urlOptions.has('replicaSet');

  if (isSRV) {
    // SRV Record is resolved upon connecting
    mongoOptions.srvHost = hosts[0];

    if (mongoOptions.directConnection) {
      throw new MongoAPIError('SRV URI does not support directConnection');
    }

    if (mongoOptions.srvMaxHosts > 0 && typeof mongoOptions.replicaSet === 'string') {
      throw new MongoParseError('Cannot use srvMaxHosts option with replicaSet');
    }

    // SRV turns on TLS by default, but users can override and turn it off
    const noUserSpecifiedTLS = !objectOptions.has('tls') && !urlOptions.has('tls');
    const noUserSpecifiedSSL = !objectOptions.has('ssl') && !urlOptions.has('ssl');
    if (noUserSpecifiedTLS && noUserSpecifiedSSL) {
      mongoOptions.tls = true;
    }
  } else {
    const userSpecifiedSrvOptions =
      urlOptions.has('srvMaxHosts') ||
      objectOptions.has('srvMaxHosts') ||
      urlOptions.has('srvServiceName') ||
      objectOptions.has('srvServiceName');

    if (userSpecifiedSrvOptions) {
      throw new MongoParseError(
        'Cannot use srvMaxHosts or srvServiceName with a non-srv connection string'

View on GitHub (pinned to 3366c21a63)

Solutions

1. Remove the replicaSet option (let SRV + SDAM discover the set).
2. Or set srvMaxHosts=0 (the default) to keep the explicit replicaSet.
3. Prefer relying on SRV-record topology discovery for Atlas-style clusters.

Example fix

// before
const c = new MongoClient('mongodb+srv://cluster.example/?srvMaxHosts=2&replicaSet=rs0');
// after
const c = new MongoClient('mongodb+srv://cluster.example/?srvMaxHosts=2');

const isSRV = uri.startsWith('mongodb+srv://');
const srvMaxHosts = Number(opts.srvMaxHosts ?? new URL(uri).searchParams.get('srvMaxHosts') ?? 0);
const hasRS = Boolean(opts.replicaSet ?? new URL(uri).searchParams.get('replicaSet'));
if (isSRV && srvMaxHosts > 0 && hasRS) {
  throw new Error('Cannot combine srvMaxHosts > 0 with replicaSet on an SRV URI');
}

When it happens

Trigger: URI like 'mongodb+srv://cluster.example/?srvMaxHosts=2&replicaSet=rs0' or options { srvMaxHosts: 2, replicaSet: 'rs0' } with a mongodb+srv:// URI.

Common situations: Adding srvMaxHosts to reduce connection fan-out on a large global cluster while retaining an explicit replicaSet name from older config.

Related errors

• Cannot combine replicaSet option with srvMaxHosts
• SRV URI does not support directConnection
• loadBalanced option not supported with a replicaSet option
• Cannot limit srv hosts with loadBalanced enabled
• Option "srvHost" must not be empty

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