mongodb/node-mongodb-native · error · MongoParseError

loadBalanced option not supported when directConnection is p

Error message

loadBalanced option not supported when directConnection is provided

What it means

Thrown by validateLoadBalancedOptions (connection_string.ts:576-578) when both loadBalanced=true and directConnection=true are set. directConnection bypasses SDAM and pins to one server's view, while loadBalanced expects to route through an external LB that may distribute across backends - the modes are contradictory.

Source

Thrown at src/connection_string.ts:577

 * - 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,
  descriptor: OptionDescriptor,
  values: unknown[]
) {
  const { target, type, transform } = descriptor;
  const name = target ?? key;

View on GitHub (pinned to 3366c21a63)

Solutions

1. Remove directConnection when using loadBalanced.
2. Or remove loadBalanced if you want a direct single-server connection.
3. Use only one of the two topology-directing flags.

Example fix

// before
const c = new MongoClient('mongodb://host/?loadBalanced=true&directConnection=true');
// after
const c = new MongoClient('mongodb://host/?loadBalanced=true');

const lb = new URL(uri).searchParams.get('loadBalanced') === 'true' || opts.loadBalanced === true;
const dc = opts.directConnection === true || new URL(uri).searchParams.get('directConnection') === 'true';
if (lb && dc) throw new Error('loadBalanced and directConnection are mutually exclusive');

When it happens

Trigger: URI like 'mongodb://host/?loadBalanced=true&directConnection=true' or options { directConnection: true } combined with a loadBalanced URI.

Common situations: Combining 'connect to one host' debugging options with a load-balanced production URI; copy-pasting an options object that includes directConnection.

Related errors

• loadBalanced option only supported with a single host in the
• loadBalanced option not supported with a replicaSet option
• 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/3c0ecf8bb2e36854.json. Report an issue: GitHub.