mongodb/node-mongodb-native · critical · MongoRuntimeError

Unexpected HostAddress ${JSON.stringify(hostAddress)}

Error message

Unexpected HostAddress ${JSON.stringify(hostAddress)}

What it means

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.

Source

Thrown at src/cmap/connect.ts:351

      (result as Document)[name] = options[name];
    }
  }
  result.keepAliveInitialDelay ??= DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS;
  result.keepAlive = true;
  result.noDelay = options.noDelay ?? true;

  if (typeof hostAddress.socketPath === 'string') {
    result.path = hostAddress.socketPath;
    return result as net.IpcNetConnectOpts;
  } else if (typeof hostAddress.host === 'string') {
    result.host = hostAddress.host;
    result.port = hostAddress.port;
    return result as net.TcpNetConnectOpts;
  } else {
    // This should never happen since we set up HostAddresses
    // But if we don't throw here the socket could hang until timeout
    // TODO(NODE-3483)
    throw new MongoRuntimeError(`Unexpected HostAddress ${JSON.stringify(hostAddress)}`);
  }
}

type MakeConnectionOptions = ConnectionOptions & { existingSocket?: Stream };

function parseSslOptions(options: MakeConnectionOptions): TLSConnectionOpts {
  const result: TLSConnectionOpts = parseConnectOptions(options);
  // Merge in valid SSL options
  for (const name of LEGAL_TLS_SOCKET_OPTIONS) {
    if (options[name] != null) {
      (result as Document)[name] = options[name];
    }
  }

  if (options.existingSocket) {
    result.socket = options.existingSocket;
  }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Capture the JSON.stringify(hostAddress) value from the error message and file a driver bug with it.
2. Avoid constructing HostAddress or ConnectionOptions by hand; use the URI parser.
3. Update to the latest driver patch release in case the bug is already fixed.
4. If patching the driver, ensure every HostAddress has either socketPath or host+port.

interface HostAddressLike { host?: string; port?: number; socketPath?: string; }
function isValidHostAddress(h: unknown): h is Required<HostAddressLike> {
  if (!h || typeof h !== 'object') return false;
  const o = h as HostAddressLike;
  return typeof o.socketPath === 'string' ||
    (typeof o.host === 'string' && typeof o.port === 'number');
}

import { MongoRuntimeError } from 'mongodb';
try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoRuntimeError && /Unexpected HostAddress/.test(e.message)) {
    // this is a driver-internal invariant violation - file a bug with the message payload
  }
  throw e;
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Option "hostAddress" is required
• client.connect did not create a topology but also did not th
• An unexpected error type: ${typeof error}
• ServerSessionPool requires a MongoClient
• Unrecognized options

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/574a0e186b1cb70e.json. Report an issue: GitHub.