{"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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/connection_string.ts#L553-L589","documentation":"Thrown by validateLoadBalancedOptions (connection_string.ts:569-572) when loadBalanced=true but the URI contains more than one host. Load-balanced mode connects through a single external load balancer front-end; multiple hosts contradict that topology.","triggerScenarios":"URI like 'mongodb://h1:27017,h2:27017/?loadBalanced=true' or a multi-host URI with the loadBalanced flag.","commonSituations":"Pointing at a load balancer VIP but listing multiple backend nodes; reusing a replica-set URI template for a load-balanced deployment.","solutions":["Use a single host (the load balancer endpoint) in the URI.","Confirm the front-end address is the load balancer, not individual mongos nodes.","If you need multiple hosts, disable loadBalanced and use SRV/replicaSet discovery."],"exampleFix":"// before\nconst c = new MongoClient('mongodb://h1:27017,h2:27017/?loadBalanced=true');\n// after\nconst c = new MongoClient('mongodb://lb.example:27017/?loadBalanced=true');","handlingStrategy":"validation","validationCode":"const lb = new URL(uri).searchParams.get('loadBalanced') === 'true' || opts.loadBalanced === true;\nconst hostCount = (uri.split('://')[1]?.split(/[/?]/)[0] ?? '').split(',').filter(Boolean).length;\nif (lb && hostCount > 1) throw new Error('loadBalanced requires a single host in the URI');","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use the load balancer's single DNS name as the only host.","Don't reuse multi-host replica-set URIs for load-balanced deployments."],"tags":["connection-string","load-balancing","topology"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}