mongodb/node-mongodb-native · critical · MongoRuntimeError

Unexpected HostAddress

Error message

Unexpected HostAddress ${JSON.stringify(hostAddress)}

What it means

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.

Solutions

1. Report as a driver bug with the JSON.stringify(hostAddress) value from the error message
2. Ensure any custom ConnectionOptions includes a properly constructed HostAddress
3. Avoid constructing HostAddress objects manually; let the driver build them from the URI

function isValidHostAddress(h: unknown): boolean {
  return h != null && (typeof (h as any).host === 'string' || typeof (h as any).socketPath === 'string');
}

try { await client.connect(); } catch (e) {
  if (e instanceof MongoRuntimeError && /Unexpected HostAddress/.test(e.message)) {
    // report driver bug; include the JSON from the message
  }
  throw e;
}

When it happens

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

Common situations: Internal driver bug; a third-party plugin that replaces HostAddress with an incompatible object; corrupted options passed to the internal connect() function.

Related errors

• Option "hostAddress" is required
• An unexpected error type
• Attempted to get a refresh token when none exists.
• Attempted to get an access token when none exists.
• Attempted to get IDP information when none exists.

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

Appendix: 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 dce7939f86)