{"record":{"id":"336d8ea989a6096e","repo":"mongodb/node-mongodb-native","slug":"cannot-use-srvmaxhosts-option-with-replicaset","errorCode":null,"errorMessage":"Cannot use srvMaxHosts option with replicaSet","messagePattern":"Cannot use srvMaxHosts option with replicaSet","errorType":"exception","errorClass":"MongoParseError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":477,"sourceCode":"  }\n\n  // Potential SRV Overrides and SRV connection string validations\n\n  mongoOptions.userSpecifiedAuthSource =\n    objectOptions.has('authSource') || urlOptions.has('authSource');\n  mongoOptions.userSpecifiedReplicaSet =\n    objectOptions.has('replicaSet') || urlOptions.has('replicaSet');\n\n  if (isSRV) {\n    // SRV Record is resolved upon connecting\n    mongoOptions.srvHost = hosts[0];\n\n    if (mongoOptions.directConnection) {\n      throw new MongoAPIError('SRV URI does not support directConnection');\n    }\n\n    if (mongoOptions.srvMaxHosts > 0 && typeof mongoOptions.replicaSet === 'string') {\n      throw new MongoParseError('Cannot use srvMaxHosts option with replicaSet');\n    }\n\n    // SRV turns on TLS by default, but users can override and turn it off\n    const noUserSpecifiedTLS = !objectOptions.has('tls') && !urlOptions.has('tls');\n    const noUserSpecifiedSSL = !objectOptions.has('ssl') && !urlOptions.has('ssl');\n    if (noUserSpecifiedTLS && noUserSpecifiedSSL) {\n      mongoOptions.tls = true;\n    }\n  } else {\n    const userSpecifiedSrvOptions =\n      urlOptions.has('srvMaxHosts') ||\n      objectOptions.has('srvMaxHosts') ||\n      urlOptions.has('srvServiceName') ||\n      objectOptions.has('srvServiceName');\n\n    if (userSpecifiedSrvOptions) {\n      throw new MongoParseError(\n        'Cannot use srvMaxHosts or srvServiceName with a non-srv connection string'","sourceCodeStart":459,"sourceCodeEnd":495,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/connection_string.ts#L459-L495","documentation":"Thrown by MongoParseError when an SRV (`mongodb+srv://`) URI sets both `srvMaxHosts` to a positive value and a `replicaSet` name. `replicaSet` already restricts which hosts the client talks to, so letting srvMaxHosts randomly subsample them would be contradictory. Check is at src/connection_string.ts:477.","triggerScenarios":"`mongodb+srv://cluster.example.mongodb.net/?srvMaxHosts=2&replicaSet=rs0` or options `{ srvMaxHosts: 2, replicaSet: 'rs0' }` with a +srv URI.","commonSituations":"Limiting the number of SRV-resolved hosts for multi-region failover while also pinning the replica-set name; leftover replicaSet option when migrating an Atlas URI to use srvMaxHosts.","solutions":["Remove `replicaSet` from the URI/options and keep `srvMaxHosts` to let the driver subsample SRV results.","Alternatively, remove `srvMaxHosts` and keep `replicaSet` to let the driver use all members that match the set name."],"exampleFix":"// before\nnew MongoClient('mongodb+srv://cluster.example.mongodb.net/?srvMaxHosts=2&replicaSet=rs0')\n\n// after\nnew MongoClient('mongodb+srv://cluster.example.mongodb.net/?srvMaxHosts=2')","handlingStrategy":"validation","validationCode":"function assertNoSrvMaxWithRs(options = {}) {\n  if (options.srvMaxHosts > 0 && typeof options.replicaSet === 'string') {\n    throw new Error('srvMaxHosts and replicaSet are mutually exclusive.');\n  }\n}","typeGuard":null,"tryCatchPattern":"try { new MongoClient(uri, options); } catch (e) { if (e instanceof MongoParseError && /srvMaxHosts option with replicaSet/.test(e.message)) { delete options.replicaSet; } else throw e; }","preventionTips":["Decide whether you want SRV sub-sampling (srvMaxHosts) or replica-set pinning (replicaSet) — not both.","Review Atlas-style URIs you copy: many include replicaSet by default."],"tags":["connection-string","srv","replica-set","topology"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}