mongodb/node-mongodb-native · error · MongoParseError

loadBalanced option only supported with a single host in…

Error message

loadBalanced option only supported with a single host in the URI

What it means

Thrown by MongoParseError (constant LB_SINGLE_HOST_ERROR) inside `validateLoadBalancedOptions` at src/connection_string.ts:571 when `loadBalanced=true` and the URI lists more than one host. A load-balanced deployment fronts a single mongos/LoaderBalanced endpoint behind which there can be many servers, so the client expects exactly one host in the URI.

Solutions

1. Reduce the URI to exactly one host (the load balancer or single mongos endpoint) and keep `loadBalanced=true`.
2. If you want to talk to multiple mongos routers with client-side selection, drop `loadBalanced` and let SDAM handle them.

Example fix

// before
new MongoClient('mongodb://h1:27017,h2:27017/?loadBalanced=true')

// after
new MongoClient('mongodb://lb.example.com:27017/?loadBalanced=true')

function assertLbSingleHost(uri, options = {}) {
  const lb = options.loadBalanced ?? /loadBalanced=true/i.test(uri);
  if (!lb) return;
  const hosts = uri.split('://')[1]?.split('/')[0].split('?')[0].split(',').filter(Boolean);
  if (hosts.length > 1) throw new Error('loadBalanced requires a single host in the URI.');
}

try { new MongoClient(uri); } catch (e) { if (e instanceof MongoParseError && /loadBalanced option only supported with a single host/.test(e.message)) { /* trim URI to one host */ } else throw e; }

When it happens

Trigger: `mongodb://h1:27017,h2:27017/?loadBalanced=true` or a multi-host +srv URI with loadBalanced set.

Common situations: Pointing the driver at multiple mongos routers thinking loadBalanced will round-robin them; reusing a replica-set URI and flipping on loadBalanced.

Related errors

• Cannot limit srv hosts with loadBalanced enabled
• loadBalanced option not supported when directConnection is…
• loadBalanced option not supported with a replicaSet option
• Cannot use srvMaxHosts option with replicaSet
• Cannot use srvMaxHosts or srvServiceName with a non-srv…

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

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