{"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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cmap/connect.ts#L124-L160","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconst client = new MongoClient('mongodb://lb-host:27017/?loadBalanced=true'); // LB fronts a replica set\n\n// after\nconst client = new MongoClient('mongodb://rs-host:27017/?replicaSet=rs0');","handlingStrategy":"validation","validationCode":"function assertLoadBalancedTarget(uri: string, opts: any) {\n  if (opts.loadBalanced === true || /loadBalanced=true/.test(uri)) {\n    // Only enable when you KNOW the endpoint is mongos (>=5.0) behind an L4 LB\n    if (!process.env.MONGOS_BEHIND_LB) {\n      throw new Error('loadBalanced=true requires a mongos behind an L4 load balancer');\n    }\n  }\n}","typeGuard":"function shouldUseLoadBalanced(deployment: { kind: 'mongos-lb' | 'rs' | 'standalone' }): boolean {\n  return deployment.kind === 'mongos-lb';\n}","tryCatchPattern":"import { MongoCompatibilityError } from 'mongodb';\ntry {\n  await client.connect();\n} catch (e) {\n  if (e instanceof MongoCompatibilityError && /load balancing mode/.test(e.message)) {\n    // strip loadBalanced and reconnect to the replica set / standalone\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["load-balanced","topology","compatibility","configuration"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}