mongodb/node-mongodb-native · critical · MongoInvalidArgumentError

Option "hostAddress" is required

Error message

Option "hostAddress" is required

What it means

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.

Solutions

1. Use new MongoClient(uri).connect() rather than calling internal connect() directly
2. If you must call connect(), ensure options.hostAddress is a HostAddress instance (e.g. HostAddress.fromHostPort('host', 27017))
3. Report as a driver bug if reached through the public API

Example fix

// before (internal misuse)
await connect({ ...opts }); // no hostAddress

// after
import { HostAddress } from 'mongodb';
await connect({ ...opts, hostAddress: HostAddress.fromHostPort('localhost', 27017) });

import { HostAddress } from 'mongodb';
if (!opts.hostAddress) {
  opts.hostAddress = HostAddress.fromHostPort('localhost', 27017);
}

function hasHostAddress(o: { hostAddress?: unknown }): boolean {
  return o.hostAddress != null;
}

When it happens

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

Common situations: Internal driver bug, a custom transport/server implementation that bypasses normal option construction, or test code that calls connect() directly.

Related errors

• Unexpected HostAddress
• Can only make Socks5 connections to TCP hosts
• Descriptors missing a type must define a transform
• No workflow provided to the OIDC auth provider.
• Unrecognized options

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/0395549321514f3f. Report an issue: GitHub.

Appendix: source

Thrown at src/cmap/connect.ts:328

  'servername',
  'session'
] as const;

/** @public */
export const LEGAL_TCP_SOCKET_OPTIONS = [
  'autoSelectFamily',
  'autoSelectFamilyAttemptTimeout',
  'keepAliveInitialDelay',
  'family',
  'hints',
  'localAddress',
  'localPort',
  'lookup'
] as const;

function parseConnectOptions(options: ConnectionOptions): SocketConnectOpts {
  const hostAddress = options.hostAddress;
  if (!hostAddress) throw new MongoInvalidArgumentError('Option "hostAddress" is required');

  const result: Partial<net.TcpNetConnectOpts & net.IpcNetConnectOpts> = {};
  for (const name of LEGAL_TCP_SOCKET_OPTIONS) {
    if (options[name] != null) {
      (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;

View on GitHub (pinned to dce7939f86)