mongodb/node-mongodb-native · error · MongoParseError

loadBalanced option only supported with a single host in the

Error message

loadBalanced option only supported with a single host in the URI

What it means

Thrown by validateLoadBalancedOptions (connection_string.ts:569-572) when loadBalanced=true but the URI contains more than one host. Load-balanced mode connects through a single external load balancer front-end; multiple hosts contradict that topology.

Source

Thrown at src/connection_string.ts:571

}

/**
 * #### Throws if LB mode is true:
 * - hosts contains more than one host
 * - there is a replicaSet name set
 * - directConnection is set
 * - if srvMaxHosts is used when an srv connection string is passed in
 *
 * @throws MongoParseError
 */
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,

View on GitHub (pinned to 3366c21a63)

Solutions

1. Use a single host (the load balancer endpoint) in the URI.
2. Confirm the front-end address is the load balancer, not individual mongos nodes.
3. If you need multiple hosts, disable loadBalanced and use SRV/replicaSet discovery.

Example fix

// before
const c = new MongoClient('mongodb://h1:27017,h2:27017/?loadBalanced=true');
// after
const c = new MongoClient('mongodb://lb.example:27017/?loadBalanced=true');

const lb = new URL(uri).searchParams.get('loadBalanced') === 'true' || opts.loadBalanced === true;
const hostCount = (uri.split('://')[1]?.split(/[/?]/)[0] ?? '').split(',').filter(Boolean).length;
if (lb && hostCount > 1) throw new Error('loadBalanced requires a single host in the URI');

When it happens

Trigger: URI like 'mongodb://h1:27017,h2:27017/?loadBalanced=true' or a multi-host URI with the loadBalanced flag.

Common situations: Pointing at a load balancer VIP but listing multiple backend nodes; reusing a replica-set URI template for a load-balanced deployment.

Related errors

• loadBalanced option not supported with a replicaSet option
• loadBalanced option not supported when directConnection is p
• Cannot limit srv hosts with loadBalanced enabled
• loadBalanced is only a valid option in the URI
• SRV URI does not support directConnection

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