{"id":"b39f4879f8cadc93","repo":"mongodb/node-mongodb-native","slug":"loadbalanced-is-only-a-valid-option-in-the-uri","errorCode":null,"errorMessage":"loadBalanced is only a valid option in the URI","messagePattern":"loadBalanced is only a valid option in the URI","errorType":"exception","errorClass":"MongoParseError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":330,"sourceCode":"  if (urlOptions.has('serverApi')) {\n    throw new MongoParseError(\n      'URI cannot contain `serverApi`, it can only be passed to the client'\n    );\n  }\n\n  const uriMechanismProperties = urlOptions.get('authMechanismProperties');\n  if (uriMechanismProperties) {\n    for (const property of uriMechanismProperties) {\n      if (/(^|,)ALLOWED_HOSTS:/.test(property as string)) {\n        throw new MongoParseError(\n          'Auth mechanism property ALLOWED_HOSTS is not allowed in the connection string.'\n        );\n      }\n    }\n  }\n\n  if (objectOptions.has('loadBalanced')) {\n    throw new MongoParseError('loadBalanced is only a valid option in the URI');\n  }\n\n  // All option collection\n\n  const allProvidedOptions = new CaseInsensitiveMap<unknown[]>();\n\n  const allProvidedKeys = new Set<string>([...urlOptions.keys(), ...objectOptions.keys()]);\n\n  for (const key of allProvidedKeys) {\n    const values = [];\n    const objectOptionValue = objectOptions.get(key);\n    if (objectOptionValue != null) {\n      values.push(objectOptionValue);\n    }\n\n    const urlValues = urlOptions.get(key) ?? [];\n    values.push(...urlValues);\n    allProvidedOptions.set(key, values);","sourceCodeStart":312,"sourceCodeEnd":348,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/connection_string.ts#L312-L348","documentation":"Thrown when `loadBalanced` is supplied in the MongoClient options object rather than in the URI. loadBalanced is treated as a URI-only option because it fundamentally describes the topology the URI points at (a single load-balanced front-end). The check at connection_string.ts:329 inspects the CaseInsensitiveMap of object options.","triggerScenarios":"Calling new MongoClient(uri, { loadBalanced: true }) or passing { loadBalanced: true } in any options object path.","commonSituations":"Connecting to a load-balanced mongos front-end and assuming all options go through the options object; refactoring a URI into structured options and moving loadBalanced along with it.","solutions":["Remove loadBalanced from the options object.","Append ?loadBalanced=true (or &loadBalanced=true) to the URI.","Ensure only a single host is in the URI when enabling loadBalanced."],"exampleFix":"// before\nconst c = new MongoClient('mongodb://lb.example:27017/', { loadBalanced: true });\n// after\nconst c = new MongoClient('mongodb://lb.example:27017/?loadBalanced=true');","handlingStrategy":"validation","validationCode":"if ('loadBalanced' in opts) {\n  throw new Error('loadBalanced belongs in the URI (?loadBalanced=true), not the options object');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Maintain a list of URI-only options (loadBalanced, srvHost) in your connection builder.","Add a TypeScript wrapper type that omits loadBalanced from the options object."],"tags":["connection-string","load-balancing","configuration"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}