{"record":{"id":"a7e00594280b9423","repo":"mongodb/node-mongodb-native","slug":"must-specify-proxyhost-if-other-proxy-options-are","errorCode":null,"errorMessage":"Must specify proxyHost if other proxy options are passed","messagePattern":"Must specify proxyHost if other proxy options are passed","errorType":"exception","errorClass":"MongoParseError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":508,"sourceCode":"      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) ?? []\n  );\n\n  if (proxyOptions.some(options => options.length > 1)) {\n    throw new MongoParseError(\n      'Proxy options cannot be specified multiple times in the connection string'\n    );\n  }","sourceCodeStart":490,"sourceCodeEnd":526,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/connection_string.ts#L490-L526","documentation":"Thrown by MongoParseError at src/connection_string.ts:508 when any of `proxyPort`, `proxyUsername`, or `proxyPassword` is set but `proxyHost` is not. The proxy host is the anchor of a proxy configuration; the other fields are meaningless without it.","triggerScenarios":"Options object `{ proxyPort: 1080, proxyUsername: 'u', proxyPassword: 'p' }` with no proxyHost, or a URI like `...?proxyPort=1080` without `proxyHost=...`.","commonSituations":"Configuring SOCKS5 proxy access and forgetting the host field; partial secrets loaded from a secret manager that supplies only credentials.","solutions":["Add `proxyHost` (the SOCKS5 proxy hostname) to the URI or options.","If you did not intend to use a proxy, remove the stray proxyPort/proxyUsername/proxyPassword options."],"exampleFix":"// before\nnew MongoClient('mongodb://host:27017/', { proxyPort: 1080, proxyUsername: 'u', proxyPassword: 'p' })\n\n// after\nnew MongoClient('mongodb://host:27017/', { proxyHost: 'proxy.internal', proxyPort: 1080, proxyUsername: 'u', proxyPassword: 'p' })","handlingStrategy":"validation","validationCode":"function assertProxyHostPresent(options = {}) {\n  const partial = options.proxyPort || options.proxyUsername || options.proxyPassword;\n  if (partial && !options.proxyHost) throw new Error('proxyHost is required when any other proxy option is set.');\n}","typeGuard":null,"tryCatchPattern":"try { new MongoClient(uri, options); } catch (e) { if (e instanceof MongoParseError && /Must specify proxyHost/.test(e.message)) { options.proxyHost = process.env.PROXY_HOST; } else throw e; }","preventionTips":["Group all four proxy options in one config builder that fails fast if proxyHost is missing.","Validate the proxy config block as a unit before constructing the client."],"tags":["connection-string","proxy","socks","configuration"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}