{"record":{"id":"0e84d96258196a0c","repo":"mongodb/node-mongodb-native","slug":"loadbalanced-option-only-supported-with-a-single-h","errorCode":null,"errorMessage":"loadBalanced option only supported with a single host in the URI","messagePattern":"loadBalanced option only supported with a single host in the URI","errorType":"exception","errorClass":"MongoParseError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":571,"sourceCode":"}\n\n/**\n * #### Throws if LB mode is true:\n * - hosts contains more than one host\n * - there is a replicaSet name set\n * - directConnection is set\n * - if srvMaxHosts is used when an srv connection string is passed in\n *\n * @throws MongoParseError\n */\nfunction validateLoadBalancedOptions(\n  hosts: HostAddress[] | string[],\n  mongoOptions: MongoOptions,\n  isSrv: boolean\n): void {\n  if (mongoOptions.loadBalanced) {\n    if (hosts.length > 1) {\n      throw new MongoParseError(LB_SINGLE_HOST_ERROR);\n    }\n    if (mongoOptions.replicaSet) {\n      throw new MongoParseError(LB_REPLICA_SET_ERROR);\n    }\n    if (mongoOptions.directConnection) {\n      throw new MongoParseError(LB_DIRECT_CONNECTION_ERROR);\n    }\n\n    if (isSrv && mongoOptions.srvMaxHosts > 0) {\n      throw new MongoParseError('Cannot limit srv hosts with loadBalanced enabled');\n    }\n  }\n  return;\n}\n\nfunction setOption(\n  mongoOptions: any,\n  key: string,","sourceCodeStart":553,"sourceCodeEnd":589,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/connection_string.ts#L553-L589","documentation":"Thrown by MongoParseError (constant LB_SINGLE_HOST_ERROR) inside `validateLoadBalancedOptions` at src/connection_string.ts:571 when `loadBalanced=true` and the URI lists more than one host. A load-balanced deployment fronts a single mongos/LoaderBalanced endpoint behind which there can be many servers, so the client expects exactly one host in the URI.","triggerScenarios":"`mongodb://h1:27017,h2:27017/?loadBalanced=true` or a multi-host +srv URI with loadBalanced set.","commonSituations":"Pointing the driver at multiple mongos routers thinking loadBalanced will round-robin them; reusing a replica-set URI and flipping on loadBalanced.","solutions":["Reduce the URI to exactly one host (the load balancer or single mongos endpoint) and keep `loadBalanced=true`.","If you want to talk to multiple mongos routers with client-side selection, drop `loadBalanced` and let SDAM handle them."],"exampleFix":"// before\nnew MongoClient('mongodb://h1:27017,h2:27017/?loadBalanced=true')\n\n// after\nnew MongoClient('mongodb://lb.example.com:27017/?loadBalanced=true')","handlingStrategy":"validation","validationCode":"function assertLbSingleHost(uri, options = {}) {\n  const lb = options.loadBalanced ?? /loadBalanced=true/i.test(uri);\n  if (!lb) return;\n  const hosts = uri.split('://')[1]?.split('/')[0].split('?')[0].split(',').filter(Boolean);\n  if (hosts.length > 1) throw new Error('loadBalanced requires a single host in the URI.');\n}","typeGuard":null,"tryCatchPattern":"try { new MongoClient(uri); } catch (e) { if (e instanceof MongoParseError && /loadBalanced option only supported with a single host/.test(e.message)) { /* trim URI to one host */ } else throw e; }","preventionTips":["In load-balanced mode, the URI host should be the LB DNS name, not a list of mongos routers.","Validate that loadBalanced URIs have exactly one host in CI."],"tags":["connection-string","load-balanced","topology"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}