mongodb/node-mongodb-native · error · MongoCompatibilityError

Driver attempted to initialize in load balancing mode, but t

Error message

Driver attempted to initialize in load balancing mode, but the server does not support this mode.

What it means

Thrown in performInitialHandshake when the client connected with loadBalanced: true but the server's hello response did not include a serviceId. A load balancer routes by serviceId; without it the deployment is not a load-balanced mongos and the driver cannot operate correctly, so it refuses to continue. This is a MongoCompatibilityError, distinct from a network or auth failure.

Source

Thrown at src/cmap/connect.ts:142

  const response = await executeHandshake(handshakeDoc, handshakeOptions);

  if (!('isWritablePrimary' in response)) {
    // Provide hello-style response document.
    response.isWritablePrimary = response[LEGACY_HELLO_COMMAND];
  }

  if (response.helloOk) {
    conn.helloOk = true;
  }

  const supportedServerErr = checkSupportedServer(response, options);
  if (supportedServerErr) {
    throw supportedServerErr;
  }

  if (options.loadBalanced) {
    if (!response.serviceId) {
      throw new MongoCompatibilityError(
        'Driver attempted to initialize in load balancing mode, ' +
          'but the server does not support this mode.'
      );
    }
  }

  // NOTE: This is metadata attached to the connection while porting away from
  //       handshake being done in the `Server` class. Likely, it should be
  //       relocated, or at very least restructured.
  conn.hello = response;
  conn.lastHelloMS = new Date().getTime() - start;

  if (!response.arbiterOnly && credentials) {
    // store the response on auth context
    authContext.response = response;

    const resolvedCredentials = credentials.resolveAuthMechanism(response);
    const provider = options.authProviders.getOrCreateProvider(

View on GitHub (pinned to 3366c21a63)

Solutions

Remove loadBalanced=true from the URI/options if the target is a standalone or replica set.
If you intend to use a load-balanced deployment, ensure the target is a mongos (>=5.0) sitting behind an L4 load balancer.
Upgrade the server to >=5.0 if you need loadBalanced mode.
Point the client at the LB fronting mongos, not directly at mongos or a replica set node.

Example fix

// before
const client = new MongoClient('mongodb://lb-host:27017/?loadBalanced=true'); // LB fronts a replica set

// after
const client = new MongoClient('mongodb://rs-host:27017/?replicaSet=rs0');

Defensive patterns

Strategy: validation

Validate before calling

function assertLoadBalancedTarget(uri: string, opts: any) {
  if (opts.loadBalanced === true || /loadBalanced=true/.test(uri)) {
    // Only enable when you KNOW the endpoint is mongos (>=5.0) behind an L4 LB
    if (!process.env.MONGOS_BEHIND_LB) {
      throw new Error('loadBalanced=true requires a mongos behind an L4 load balancer');
    }
  }
}

Type guard

function shouldUseLoadBalanced(deployment: { kind: 'mongos-lb' | 'rs' | 'standalone' }): boolean {
  return deployment.kind === 'mongos-lb';
}

Try / catch

import { MongoCompatibilityError } from 'mongodb';
try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoCompatibilityError && /load balancing mode/.test(e.message)) {
    // strip loadBalanced and reconnect to the replica set / standalone
  }
  throw e;
}

Prevention

Only set loadBalanced=true when the endpoint is mongos >=5.0 behind an L4 LB.
Keep per-environment URIs explicit; don't reuse an LB URI for non-LB deployments.
Document the deployment shape alongside each connection string.

When it happens

Trigger: MongoClient constructed with { loadBalanced: true } (or loadBalanced=true in the URI) connecting to a server that is not behind a load balancer or is a standalone/replica set member. Fires inside performInitialHandshake (src/cmap/connect.ts:140-147) on the first hello of every new connection in the pool.

Common situations: Copy-pasting a connection string tuned for a sharded cluster behind an LB onto a standalone or replica set; enabling loadBalanced to 'fix' routing through an external LB that fronts a regular mongod; server older than 5.0 (loadBalanced was introduced with serviceId in 5.0); typo in the URI where loadBalanced=true was left from a template.

Related errors

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