mongodb/node-mongodb-native · error · MongoParseError

loadBalanced option not supported when directConnection is…

Error message

loadBalanced option not supported when directConnection is provided

What it means

Thrown by MongoParseError (constant LB_DIRECT_CONNECTION_ERROR) at src/connection_string.ts:577 when both `loadBalanced=true` and `directConnection=true` are set. The two are incompatible topologies: directConnection bypasses SDAM against one server, while loadBalanced expects a single SDAM-managed endpoint behind a LB.

Solutions

Use only `loadBalanced=true` (remove directConnection) for an LB fronted deployment.
Use only `directConnection=true` (remove loadBalanced) to pin a single server without SDAM.

Example fix

// before
new MongoClient('mongodb://host:27017/?loadBalanced=true&directConnection=true')

// after
new MongoClient('mongodb://host:27017/?loadBalanced=true')

Defensive patterns

Strategy: validation

Validate before calling

function assertNoLbPlusDirect(options = {}, uri = '') {
  const lb = options.loadBalanced ?? /loadBalanced=true/i.test(uri);
  const dc = options.directConnection ?? /directConnection=true/i.test(uri);
  if (lb && dc) throw new Error('loadBalanced and directConnection cannot both be set.');
}

Try / catch

try { new MongoClient(uri, options); } catch (e) { if (e instanceof MongoParseError && /loadBalanced option not supported when directConnection/.test(e.message)) { delete options.directConnection; } else throw e; }

Prevention

Maintain an allow-list of option combinations; reject conflicting topology flags at config-load time.
Document which topology each flag belongs to so operators do not stack them.

When it happens

Trigger: URI `...?loadBalanced=true&directConnection=true` or options `{ loadBalanced: true, directConnection: true }`.

Common situations: Combining flags while experimenting; copying both options from docs/Stack Overflow examples into the same URI.

Related errors

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

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