mongodb/node-mongodb-native · error · MongoCompatibilityError

Driver attempted to initialize in load balancing mode, but…

Error message

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

What it means

Thrown as a MongoCompatibilityError in performInitialHandshake() when options.loadBalanced is true but the server's hello/handshake response has no serviceId field. Load-balanced mode (behind an LB such as Atlas LB or mongos) requires the server to advertise a serviceId so the driver can route sessions; its absence means the endpoint is not a load-balanced mongos.

Solutions

Only set loadBalanced=true when connecting through a load balancer to mongos (Atlas LB) running MongoDB 5.0+
Remove loadBalanced=true (or set it false) for direct connections to standalone/replica-set members
Verify the LB routes to mongos instances and that the server version advertises serviceId

Example fix

// before
const client = new MongoClient('mongodb://host:27017/db?loadBalanced=true');

// after (direct connection)
const client = new MongoClient('mongodb://host:27017/db?directConnection=true');

Defensive patterns

Strategy: validation

Validate before calling

const lb = new URL(uri).searchParams.get('loadBalanced');
if (lb === 'true' && !isBehindLoadBalancer) {
  throw new Error('loadBalanced=true requires a mongos behind an LB (MongoDB 5.0+)');
}

Prevention

Only enable loadBalanced when connecting through an LB to mongos (Atlas LB) on MongoDB 5.0+
Use directConnection=true for single-node direct connections
Document the topology in the connection string so operators do not flip loadBalanced

When it happens

Trigger: Connecting with loadBalanced=true (either via the ?loadBalanced=true URI option or the MongoClient option) to a server that is not behind a load balancer / not a mongos that advertises serviceId. The check runs right after the handshake response is received and checkSupportedServer passes.

Common situations: Setting loadBalanced=true by mistake against a standalone or replica set; pointing at a load balancer that fronts a non-mongos; server version too old to support load-balanced mode (< 5.0).

Related errors

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

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