mongodb/node-mongodb-native · error · MongoParseError

loadBalanced is only a valid option in the URI

Error message

loadBalanced is only a valid option in the URI

What it means

Thrown when `loadBalanced` is supplied in the MongoClient options object rather than in the URI. loadBalanced is treated as a URI-only option because it fundamentally describes the topology the URI points at (a single load-balanced front-end). The check at connection_string.ts:329 inspects the CaseInsensitiveMap of object options.

Source

Thrown at src/connection_string.ts:330

  if (urlOptions.has('serverApi')) {
    throw new MongoParseError(
      'URI cannot contain `serverApi`, it can only be passed to the client'
    );
  }

  const uriMechanismProperties = urlOptions.get('authMechanismProperties');
  if (uriMechanismProperties) {
    for (const property of uriMechanismProperties) {
      if (/(^|,)ALLOWED_HOSTS:/.test(property as string)) {
        throw new MongoParseError(
          'Auth mechanism property ALLOWED_HOSTS is not allowed in the connection string.'
        );
      }
    }
  }

  if (objectOptions.has('loadBalanced')) {
    throw new MongoParseError('loadBalanced is only a valid option in the URI');
  }

  // All option collection

  const allProvidedOptions = new CaseInsensitiveMap<unknown[]>();

  const allProvidedKeys = new Set<string>([...urlOptions.keys(), ...objectOptions.keys()]);

  for (const key of allProvidedKeys) {
    const values = [];
    const objectOptionValue = objectOptions.get(key);
    if (objectOptionValue != null) {
      values.push(objectOptionValue);
    }

    const urlValues = urlOptions.get(key) ?? [];
    values.push(...urlValues);
    allProvidedOptions.set(key, values);

View on GitHub (pinned to 3366c21a63)

Solutions

1. Remove loadBalanced from the options object.
2. Append ?loadBalanced=true (or &loadBalanced=true) to the URI.
3. Ensure only a single host is in the URI when enabling loadBalanced.

Example fix

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

if ('loadBalanced' in opts) {
  throw new Error('loadBalanced belongs in the URI (?loadBalanced=true), not the options object');
}

When it happens

Trigger: Calling new MongoClient(uri, { loadBalanced: true }) or passing { loadBalanced: true } in any options object path.

Common situations: Connecting to a load-balanced mongos front-end and assuming all options go through the options object; refactoring a URI into structured options and moving loadBalanced along with it.

Related errors

• URI cannot contain `serverApi`, it can only be passed to the
• All values of tls/ssl must be the same.
• ${optionWord} ${Array.from(unsupportedOptions).join(', ')} $
• SRV URI does not support directConnection
• Cannot use srvMaxHosts or srvServiceName with a non-srv conn

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