mongodb/node-mongodb-native · error · MongoParseError

Cannot use srvMaxHosts option with replicaSet

Error message

Cannot use srvMaxHosts option with replicaSet

What it means

Thrown by MongoParseError when an SRV (`mongodb+srv://`) URI sets both `srvMaxHosts` to a positive value and a `replicaSet` name. `replicaSet` already restricts which hosts the client talks to, so letting srvMaxHosts randomly subsample them would be contradictory. Check is at src/connection_string.ts:477.

Solutions

1. Remove `replicaSet` from the URI/options and keep `srvMaxHosts` to let the driver subsample SRV results.
2. Alternatively, remove `srvMaxHosts` and keep `replicaSet` to let the driver use all members that match the set name.

Example fix

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

// after
new MongoClient('mongodb+srv://cluster.example.mongodb.net/?srvMaxHosts=2')

function assertNoSrvMaxWithRs(options = {}) {
  if (options.srvMaxHosts > 0 && typeof options.replicaSet === 'string') {
    throw new Error('srvMaxHosts and replicaSet are mutually exclusive.');
  }
}

try { new MongoClient(uri, options); } catch (e) { if (e instanceof MongoParseError && /srvMaxHosts option with replicaSet/.test(e.message)) { delete options.replicaSet; } else throw e; }

When it happens

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

Common situations: Limiting the number of SRV-resolved hosts for multi-region failover while also pinning the replica-set name; leftover replicaSet option when migrating an Atlas URI to use srvMaxHosts.

Related errors

• Cannot combine replicaSet option with srvMaxHosts
• Cannot limit srv hosts with loadBalanced enabled
• Cannot use srvMaxHosts or srvServiceName with a non-srv…
• loadBalanced option not supported with a replicaSet option
• SRV URI does not support directConnection

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

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