mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Option "hostAddress" is required

Error message

Option "hostAddress" is required

What it means

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.

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 3366c21a63)

Solutions

1. Verify the connection string contains at least one host: 'mongodb://host:27017'.
2. For mongodb+srv:// URIs, confirm the DNS SRV record resolves to at least one target.
3. Avoid constructing internal ConnectionOptions/Server objects directly; always go through MongoClient.
4. If using a custom SDAM setup, ensure every ConnectionOptions has hostAddress set.

Example fix

// before
const client = new MongoClient('mongodb://');

// after
const client = new MongoClient('mongodb://localhost:27017');

function validateUriHasHost(uri: string) {
  const m = uri.match(/^mongodb(?:\+srv)?:\/\/(.+?)(?:\/|\?|$)/);
  if (!m || !m[1] || !m[1].trim()) {
    throw new Error('Connection string must contain at least one host');
  }
}

function isNonEmptyConnectionString(uri: string): boolean {
  return /^mongodb(\+srv)?:\/\/[^/?#]+/.test(uri);
}

import { MongoInvalidArgumentError } from 'mongodb';
try {
  const c = new MongoClient(uri);
  await c.connect();
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /hostAddress/.test(e.message)) {
    // URI had no host; prompt user / fall back to default
  }
  throw e;
}

When it happens

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

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

Related errors

• Unexpected HostAddress ${JSON.stringify(hostAddress)}
• Can only make Socks5 connections to TCP hosts
• Cannot set both proxyOptions and kmsConnectCallback
• Can only provide a custom AWS credential provider when the s
• `cryptSharedLibRequired` set but no crypt_shared library loa

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