{"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":"error","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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cmap/connect.ts#L310-L346","documentation":"Thrown in parseConnectOptions when options.hostAddress is falsy. HostAddress is built from the URI's host:port list during MongoClient construction; reaching this point with no hostAddress means the connection options were constructed programmatically without a host, or the URI parsing produced an empty host list.","triggerScenarios":"Internal: somewhere in SDAM the ConnectionOptions object handed to makeConnection had no hostAddress set. Triggered when makeSocket/makeSocks5Connection calls parseConnectOptions (src/cmap/connect.ts:326-328). Almost always indicates a programming error in code that builds ConnectionOptions directly, or a bug in URI parsing for an empty mongodb:// URI.","commonSituations":"An empty or malformed connection string like 'mongodb://' with no hosts; programmatically constructing a Server/Topology with options that omit hostAddress; a driver bug in a non-standard URI form (e.g. mongodb+srv:// with a DNS record that resolved to zero hosts).","solutions":["Verify the connection string contains at least one host: 'mongodb://host:27017'.","For mongodb+srv:// URIs, confirm the DNS SRV record resolves to at least one target.","Avoid constructing internal ConnectionOptions/Server objects directly; always go through MongoClient.","If using a custom SDAM setup, ensure every ConnectionOptions has hostAddress set."],"exampleFix":"// before\nconst client = new MongoClient('mongodb://');\n\n// after\nconst client = new MongoClient('mongodb://localhost:27017');","handlingStrategy":"validation","validationCode":"function validateUriHasHost(uri: string) {\n  const m = uri.match(/^mongodb(?:\\+srv)?:\\/\\/(.+?)(?:\\/|\\?|$)/);\n  if (!m || !m[1] || !m[1].trim()) {\n    throw new Error('Connection string must contain at least one host');\n  }\n}","typeGuard":"function isNonEmptyConnectionString(uri: string): boolean {\n  return /^mongodb(\\+srv)?:\\/\\/[^/?#]+/.test(uri);\n}","tryCatchPattern":"import { MongoInvalidArgumentError } from 'mongodb';\ntry {\n  const c = new MongoClient(uri);\n  await c.connect();\n} catch (e) {\n  if (e instanceof MongoInvalidArgumentError && /hostAddress/.test(e.message)) {\n    // URI had no host; prompt user / fall back to default\n  }\n  throw e;\n}","preventionTips":["Validate connection strings at app startup before constructing MongoClient.","For mongodb+srv://, check DNS resolution of the SRV record.","Never hand-construct internal ConnectionOptions; go through MongoClient."],"tags":["connection","configuration","uri","host-address"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}