mongodb/node-mongodb-native · error · MongoParseError

Cannot limit srv hosts with loadBalanced enabled

Error message

Cannot limit srv hosts with loadBalanced enabled

What it means

Thrown by MongoParseError at src/connection_string.ts:581 when an SRV URI has `loadBalanced=true` and `srvMaxHosts` set to a positive value. srvMaxHosts would randomly subsample SRV results, but load-balanced mode expects the SRV query to yield the single load-balancer endpoint without sub-sampling.

Solutions

1. Remove `srvMaxHosts` when running loadBalanced against an SRV hostname.
2. If you need srvMaxHosts limiting, drop `loadBalanced` and use a non-LB topology.

Example fix

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

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

function assertNoLbSrvLimit(uri, options = {}) {
  const isSrv = uri.startsWith('mongodb+srv://');
  const lb = options.loadBalanced ?? /loadBalanced=true/i.test(uri);
  if (isSrv && lb && (options.srvMaxHosts ?? 0) > 0) {
    throw new Error('srvMaxHosts must be 0/unset for load-balanced SRV connections.');
  }
}

try { new MongoClient(uri, options); } catch (e) { if (e instanceof MongoParseError && /Cannot limit srv hosts with loadBalanced/.test(e.message)) { delete options.srvMaxHosts; } else throw e; }

When it happens

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

Common situations: Trying to combine host-limiting (used for sharded/multi-region tuning) with a load-balanced deployment; copy-paste of an srvMaxHosts-tuned URI onto an LB endpoint.

Related errors

• Cannot use srvMaxHosts option with replicaSet
• Cannot use srvMaxHosts or srvServiceName with a non-srv…
• loadBalanced option not supported when directConnection is…
• loadBalanced option not supported with a replicaSet option
• loadBalanced option only supported with a single host in…

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

Appendix: source

Thrown at src/connection_string.ts:581

 */
function validateLoadBalancedOptions(
  hosts: HostAddress[] | string[],
  mongoOptions: MongoOptions,
  isSrv: boolean
): void {
  if (mongoOptions.loadBalanced) {
    if (hosts.length > 1) {
      throw new MongoParseError(LB_SINGLE_HOST_ERROR);
    }
    if (mongoOptions.replicaSet) {
      throw new MongoParseError(LB_REPLICA_SET_ERROR);
    }
    if (mongoOptions.directConnection) {
      throw new MongoParseError(LB_DIRECT_CONNECTION_ERROR);
    }

    if (isSrv && mongoOptions.srvMaxHosts > 0) {
      throw new MongoParseError('Cannot limit srv hosts with loadBalanced enabled');
    }
  }
  return;
}

function setOption(
  mongoOptions: any,
  key: string,
  descriptor: OptionDescriptor,
  values: unknown[]
) {
  const { target, type, transform } = descriptor;
  const name = target ?? key;

  switch (type) {
    case 'boolean':
      mongoOptions[name] = getBoolean(name, values[0]);
      break;

View on GitHub (pinned to dce7939f86)