{"id":"3c0ecf8bb2e36854","repo":"mongodb/node-mongodb-native","slug":"loadbalanced-option-not-supported-when-directconne","errorCode":null,"errorMessage":"loadBalanced option not supported when directConnection is provided","messagePattern":"loadBalanced option not supported when directConnection is provided","errorType":"exception","errorClass":"MongoParseError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":577,"sourceCode":" * - 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,\n  descriptor: OptionDescriptor,\n  values: unknown[]\n) {\n  const { target, type, transform } = descriptor;\n  const name = target ?? key;\n","sourceCodeStart":559,"sourceCodeEnd":595,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/connection_string.ts#L559-L595","documentation":"Thrown by validateLoadBalancedOptions (connection_string.ts:576-578) when both loadBalanced=true and directConnection=true are set. directConnection bypasses SDAM and pins to one server's view, while loadBalanced expects to route through an external LB that may distribute across backends - the modes are contradictory.","triggerScenarios":"URI like 'mongodb://host/?loadBalanced=true&directConnection=true' or options { directConnection: true } combined with a loadBalanced URI.","commonSituations":"Combining 'connect to one host' debugging options with a load-balanced production URI; copy-pasting an options object that includes directConnection.","solutions":["Remove directConnection when using loadBalanced.","Or remove loadBalanced if you want a direct single-server connection.","Use only one of the two topology-directing flags."],"exampleFix":"// before\nconst c = new MongoClient('mongodb://host/?loadBalanced=true&directConnection=true');\n// after\nconst c = new MongoClient('mongodb://host/?loadBalanced=true');","handlingStrategy":"validation","validationCode":"const lb = new URL(uri).searchParams.get('loadBalanced') === 'true' || opts.loadBalanced === true;\nconst dc = opts.directConnection === true || new URL(uri).searchParams.get('directConnection') === 'true';\nif (lb && dc) throw new Error('loadBalanced and directConnection are mutually exclusive');","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat directConnection as a local-only debugging flag.","Strip debugging flags before promoting config to production."],"tags":["connection-string","load-balancing","topology"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}