{"id":"574a0e186b1cb70e","repo":"mongodb/node-mongodb-native","slug":"unexpected-hostaddress-json-stringify-hostaddres","errorCode":null,"errorMessage":"Unexpected HostAddress ${JSON.stringify(hostAddress)}","messagePattern":"Unexpected HostAddress (.+?)","errorType":"exception","errorClass":"MongoRuntimeError","httpStatus":null,"severity":"critical","filePath":"src/cmap/connect.ts","lineNumber":351,"sourceCode":"      (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;\n  } else {\n    // This should never happen since we set up HostAddresses\n    // But if we don't throw here the socket could hang until timeout\n    // TODO(NODE-3483)\n    throw new MongoRuntimeError(`Unexpected HostAddress ${JSON.stringify(hostAddress)}`);\n  }\n}\n\ntype MakeConnectionOptions = ConnectionOptions & { existingSocket?: Stream };\n\nfunction parseSslOptions(options: MakeConnectionOptions): TLSConnectionOpts {\n  const result: TLSConnectionOpts = parseConnectOptions(options);\n  // Merge in valid SSL options\n  for (const name of LEGAL_TLS_SOCKET_OPTIONS) {\n    if (options[name] != null) {\n      (result as Document)[name] = options[name];\n    }\n  }\n\n  if (options.existingSocket) {\n    result.socket = options.existingSocket;\n  }\n","sourceCodeStart":333,"sourceCodeEnd":369,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cmap/connect.ts#L333-L369","documentation":"Thrown in parseConnectOptions when hostAddress exists but has neither a string socketPath nor a string host. The comment above it says 'This should never happen since we set up HostAddresses', and the throw exists specifically to avoid hanging on a socket connect until timeout. This is a MongoRuntimeError reserved for an internal invariant violation.","triggerScenarios":"Only if a HostAddress object was constructed with neither socketPath nor host - effectively a driver-internal bug or a tampered HostAddress. Reached in the final else branch of parseConnectOptions (src/cmap/connect.ts:347-352).","commonSituations":"A driver bug where HostAddress.from() produced an incomplete object; passing a custom/malformed hostAddress through internal APIs; memory corruption; a third-party patch that constructs HostAddress incorrectly. End users essentially never trigger this through public options.","solutions":["Capture the JSON.stringify(hostAddress) value from the error message and file a driver bug with it.","Avoid constructing HostAddress or ConnectionOptions by hand; use the URI parser.","Update to the latest driver patch release in case the bug is already fixed.","If patching the driver, ensure every HostAddress has either socketPath or host+port."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"interface HostAddressLike { host?: string; port?: number; socketPath?: string; }\nfunction isValidHostAddress(h: unknown): h is Required<HostAddressLike> {\n  if (!h || typeof h !== 'object') return false;\n  const o = h as HostAddressLike;\n  return typeof o.socketPath === 'string' ||\n    (typeof o.host === 'string' && typeof o.port === 'number');\n}","tryCatchPattern":"import { MongoRuntimeError } from 'mongodb';\ntry {\n  await client.connect();\n} catch (e) {\n  if (e instanceof MongoRuntimeError && /Unexpected HostAddress/.test(e.message)) {\n    // this is a driver-internal invariant violation - file a bug with the message payload\n  }\n  throw e;\n}","preventionTips":["Do not construct HostAddress or ConnectionOptions manually in app code.","Always source host addresses from MongoClient URI parsing.","Upgrade the driver if you hit this; it indicates an internal bug."],"tags":["connection","runtime","host-address","internal"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}