{"record":{"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/dce7939f86fb283e167ad709955abedb7bf23124/src/cmap/connect.ts#L333-L369","documentation":"Thrown as a MongoRuntimeError in parseConnectOptions() when hostAddress exists but has neither a string socketPath nor a string host property. The comment ('This should never happen since we set up HostAddresses') marks this as a defensive guard: without a host or path the socket would hang until connectTimeoutMS, so the driver fails fast instead. Reachable only via internal bugs.","triggerScenarios":"A HostAddress object (or something masquerading as one) that is missing both .socketPath and .host. Would require a driver bug in HostAddress construction, a custom HostAddress subclass, or direct internal API misuse.","commonSituations":"Internal driver bug; a third-party plugin that replaces HostAddress with an incompatible object; corrupted options passed to the internal connect() function.","solutions":["Report as a driver bug with the JSON.stringify(hostAddress) value from the error message","Ensure any custom ConnectionOptions includes a properly constructed HostAddress","Avoid constructing HostAddress objects manually; let the driver build them from the URI"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isValidHostAddress(h: unknown): boolean {\n  return h != null && (typeof (h as any).host === 'string' || typeof (h as any).socketPath === 'string');\n}","tryCatchPattern":"try { await client.connect(); } catch (e) {\n  if (e instanceof MongoRuntimeError && /Unexpected HostAddress/.test(e.message)) {\n    // report driver bug; include the JSON from the message\n  }\n  throw e;\n}","preventionTips":["Do not replace HostAddress with custom incompatible objects","Let the driver construct HostAddress from the URI","Report occurrences with the hostAddress JSON included in the error"],"tags":["connection","internal","host-address","invariant"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}