{"record":{"id":"0395549321514f3f","repo":"mongodb/node-mongodb-native","slug":"option-hostaddress-is-required","errorCode":null,"errorMessage":"Option \"hostAddress\" is required","messagePattern":"Option \"hostAddress\" is required","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"critical","filePath":"src/cmap/connect.ts","lineNumber":328,"sourceCode":"  'servername',\n  'session'\n] as const;\n\n/** @public */\nexport const LEGAL_TCP_SOCKET_OPTIONS = [\n  'autoSelectFamily',\n  'autoSelectFamilyAttemptTimeout',\n  'keepAliveInitialDelay',\n  'family',\n  'hints',\n  'localAddress',\n  'localPort',\n  'lookup'\n] as const;\n\nfunction parseConnectOptions(options: ConnectionOptions): SocketConnectOpts {\n  const hostAddress = options.hostAddress;\n  if (!hostAddress) throw new MongoInvalidArgumentError('Option \"hostAddress\" is required');\n\n  const result: Partial<net.TcpNetConnectOpts & net.IpcNetConnectOpts> = {};\n  for (const name of LEGAL_TCP_SOCKET_OPTIONS) {\n    if (options[name] != null) {\n      (result as Document)[name] = options[name];\n    }\n  }\n  result.keepAliveInitialDelay ??= DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS;\n  result.keepAlive = true;\n  result.noDelay = options.noDelay ?? true;\n\n  if (typeof hostAddress.socketPath === 'string') {\n    result.path = hostAddress.socketPath;\n    return result as net.IpcNetConnectOpts;\n  } else if (typeof hostAddress.host === 'string') {\n    result.host = hostAddress.host;\n    result.port = hostAddress.port;\n    return result as net.TcpNetConnectOpts;","sourceCodeStart":310,"sourceCodeEnd":346,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/cmap/connect.ts#L310-L346","documentation":"Thrown as a MongoInvalidArgumentError in parseConnectOptions() when options.hostAddress is falsy. parseConnectOptions() translates connection options into Node net.TcpNetConnectOpts/net.IpcNetConnectOpts; without a host address the driver cannot open a socket. Normally the MongoClient/Topology constructs HostAddress objects from the URI, so a missing hostAddress means the options were built incorrectly.","triggerScenarios":"Calling connect() (an @internal function) directly with a ConnectionOptions object lacking hostAddress, or a bug in the topology/server layer that fails to set hostAddress on the connection options. Not reachable from the standard new MongoClient(uri).connect() path.","commonSituations":"Internal driver bug, a custom transport/server implementation that bypasses normal option construction, or test code that calls connect() directly.","solutions":["Use new MongoClient(uri).connect() rather than calling internal connect() directly","If you must call connect(), ensure options.hostAddress is a HostAddress instance (e.g. HostAddress.fromHostPort('host', 27017))","Report as a driver bug if reached through the public API"],"exampleFix":"// before (internal misuse)\nawait connect({ ...opts }); // no hostAddress\n\n// after\nimport { HostAddress } from 'mongodb';\nawait connect({ ...opts, hostAddress: HostAddress.fromHostPort('localhost', 27017) });","handlingStrategy":"validation","validationCode":"import { HostAddress } from 'mongodb';\nif (!opts.hostAddress) {\n  opts.hostAddress = HostAddress.fromHostPort('localhost', 27017);\n}","typeGuard":"function hasHostAddress(o: { hostAddress?: unknown }): boolean {\n  return o.hostAddress != null;\n}","tryCatchPattern":null,"preventionTips":["Use new MongoClient(uri).connect() instead of the internal connect() function","Always set hostAddress when constructing ConnectionOptions manually","Let the driver build HostAddress from the connection string"],"tags":["connection","internal","configuration","host-address"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}