{"record":{"id":"3e45b17178b817f6","repo":"mongodb/node-mongodb-native","slug":"driver-attempted-to-initialize-in-load-balancing-m","errorCode":null,"errorMessage":"Driver attempted to initialize in load balancing mode, but the server does not support this mode.","messagePattern":"Driver attempted to initialize in load balancing mode, but the server does not support this mode\\.","errorType":"exception","errorClass":"MongoCompatibilityError","httpStatus":null,"severity":"error","filePath":"src/cmap/connect.ts","lineNumber":142,"sourceCode":"  const response = await executeHandshake(handshakeDoc, handshakeOptions);\n\n  if (!('isWritablePrimary' in response)) {\n    // Provide hello-style response document.\n    response.isWritablePrimary = response[LEGACY_HELLO_COMMAND];\n  }\n\n  if (response.helloOk) {\n    conn.helloOk = true;\n  }\n\n  const supportedServerErr = checkSupportedServer(response, options);\n  if (supportedServerErr) {\n    throw supportedServerErr;\n  }\n\n  if (options.loadBalanced) {\n    if (!response.serviceId) {\n      throw new MongoCompatibilityError(\n        'Driver attempted to initialize in load balancing mode, ' +\n          'but the server does not support this mode.'\n      );\n    }\n  }\n\n  // NOTE: This is metadata attached to the connection while porting away from\n  //       handshake being done in the `Server` class. Likely, it should be\n  //       relocated, or at very least restructured.\n  conn.hello = response;\n  conn.lastHelloMS = new Date().getTime() - start;\n\n  if (!response.arbiterOnly && credentials) {\n    // store the response on auth context\n    authContext.response = response;\n\n    const resolvedCredentials = credentials.resolveAuthMechanism(response);\n    const provider = options.authProviders.getOrCreateProvider(","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/cmap/connect.ts#L124-L160","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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"],"exampleFix":"// before\nconst client = new MongoClient('mongodb://host:27017/db?loadBalanced=true');\n\n// after (direct connection)\nconst client = new MongoClient('mongodb://host:27017/db?directConnection=true');","handlingStrategy":"validation","validationCode":"const lb = new URL(uri).searchParams.get('loadBalanced');\nif (lb === 'true' && !isBehindLoadBalancer) {\n  throw new Error('loadBalanced=true requires a mongos behind an LB (MongoDB 5.0+)');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["load-balancing","compatibility","configuration","topology"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}