{"record":{"id":"69329b59135295fb","repo":"mongodb/node-mongodb-native","slug":"directconnection-option-requires-exactly-one-host","errorCode":null,"errorMessage":"directConnection option requires exactly one host","messagePattern":"directConnection option requires exactly one host","errorType":"exception","errorClass":"MongoParseError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":501,"sourceCode":"    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'\n      );\n    }\n  }\n\n  if (mongoOptions.directConnection && mongoOptions.hosts.length !== 1) {\n    throw new MongoParseError('directConnection option requires exactly one host');\n  }\n\n  if (\n    !mongoOptions.proxyHost &&\n    (mongoOptions.proxyPort || mongoOptions.proxyUsername || mongoOptions.proxyPassword)\n  ) {\n    throw new MongoParseError('Must specify proxyHost if other proxy options are passed');\n  }\n\n  if (\n    (mongoOptions.proxyUsername && !mongoOptions.proxyPassword) ||\n    (!mongoOptions.proxyUsername && mongoOptions.proxyPassword)\n  ) {\n    throw new MongoParseError('Can only specify both of proxy username/password or neither');\n  }\n\n  const proxyOptions = ['proxyHost', 'proxyPort', 'proxyUsername', 'proxyPassword'].map(\n    key => urlOptions.get(key) ?? []","sourceCodeStart":483,"sourceCodeEnd":519,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/connection_string.ts#L483-L519","documentation":"Thrown by MongoParseError at src/connection_string.ts:501 when `directConnection=true` is set but the URI contains zero or more than one host. Direct connection pins the client to exactly one server, so multiple hosts (or none) contradict the option.","triggerScenarios":"`mongodb://h1:27017,h2:27017/?directConnection=true`, or an empty hosts list with `{ directConnection: true }`, or a trailing comma producing an empty host.","commonSituations":"Reusing a multi-host replica-set URI and adding `directConnection=true` for debugging; YAML env var templating that injects a host list of varying length.","solutions":["Keep exactly one host in the URI: `mongodb://oneHost:27017/?directConnection=true`.","If you want to connect to multiple hosts, remove `directConnection`."],"exampleFix":"// before\nnew MongoClient('mongodb://h1:27017,h2:27017/?directConnection=true')\n\n// after (direct to one host)\nnew MongoClient('mongodb://h1:27017/?directConnection=true')","handlingStrategy":"validation","validationCode":"function assertDirectSingleHost(uri, options = {}) {\n  const direct = options.directConnection ?? /directConnection=true/i.test(uri);\n  if (!direct) return;\n  const hostPart = uri.split('://')[1]?.split('/')[0].split('?')[0];\n  const hostCount = hostCount = hostPart.split(',').filter(Boolean).length;\n  if (hostCount !== 1) throw new Error('directConnection requires exactly one host.');\n}","typeGuard":null,"tryCatchPattern":"try { new MongoClient(uri); } catch (e) { if (e instanceof MongoParseError && /directConnection option requires exactly one host/.test(e.message)) { /* pick one host or drop directConnection */ } else throw e; }","preventionTips":["Do not set directConnection on URIs whose host list is templated and variable in length.","Treat directConnection as a single-host debugging tool, not a default."],"tags":["connection-string","direct-connection","topology"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}