{"record":{"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/dce7939f86fb283e167ad709955abedb7bf23124/src/connection_string.ts#L312-L348","documentation":"loadBalanced is a topology property baked into the URI per the load-balancer spec; it must be set there (e.g. '?loadBalanced=true') so all clients sharing the URI see the same topology. Passing it via the options object is rejected because it would let per-client code disagree with the URI.","triggerScenarios":"Calling new MongoClient(uri, { loadBalanced: true }) (or false). Detected via objectOptions.has('loadBalanced').","commonSituations":"Configuring a load-balanced deployment in code rather than the URI, often because the URI is shared across services.","solutions":["Move loadBalanced into the URI query string.","Remove the loadBalanced key from the options object."],"exampleFix":"// before\nnew MongoClient('mongodb://h/db', { loadBalanced: true });\n// after\nnew MongoClient('mongodb://h/db?loadBalanced=true');","handlingStrategy":"validation","validationCode":"function assertLoadBalancedNotInOptions(opts: Record<string, unknown>) {\n  if ('loadBalanced' in opts) {\n    throw new Error('Set loadBalanced in the URI (?loadBalanced=true), not the options object');\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Bake topology-level flags (loadBalanced) into the shared URI.","Reserve the options object for per-instance behavior."],"tags":["connection-string","load-balanced","validation"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}