mongodb/node-mongodb-native · error · MongoRuntimeError

ServerDescription must be provided with a non-empty address

Error message

ServerDescription must be provided with a non-empty address

What it means

The `ServerDescription` constructor requires a non-empty address; it throws when the address is null, undefined, or an empty string (server_description.ts:102). ServerDescription is an `@internal` class used by SDAM to represent a discovered or seed server, and every description must carry a resolvable host:port address.

Source

Thrown at src/sdam/server_description.ts:103

  iscryptd: boolean;

  // NOTE: does this belong here? It seems we should gossip the cluster time at the CMAP level
  $clusterTime?: ClusterTime;

  /**
   * Create a ServerDescription
   * @internal
   *
   * @param address - The address of the server
   * @param hello - An optional hello response for this server
   */
  constructor(
    address: HostAddress | string,
    hello?: Document,
    options: ServerDescriptionOptions = {}
  ) {
    if (address == null || address === '') {
      throw new MongoRuntimeError('ServerDescription must be provided with a non-empty address');
    }

    this.address =
      typeof address === 'string'
        ? HostAddress.fromString(address).toString() // Use HostAddress to normalize
        : address.toString();
    this.type = parseServerType(hello, options);
    this.hosts = hello?.hosts?.map((host: string) => host.toLowerCase()) ?? [];
    this.passives = hello?.passives?.map((host: string) => host.toLowerCase()) ?? [];
    this.arbiters = hello?.arbiters?.map((host: string) => host.toLowerCase()) ?? [];
    this.tags = hello?.tags ?? {};
    this.minWireVersion = hello?.minWireVersion ?? 0;
    this.maxWireVersion = hello?.maxWireVersion ?? 0;
    this.roundTripTime = options?.roundTripTime ?? -1;
    this.minRoundTripTime = options?.minRoundTripTime ?? 0;
    this.lastUpdateTime = processTimeMS();
    this.lastWriteDate = hello?.lastWrite?.lastWriteDate ?? 0;
    // NOTE: This actually builds the stack string instead of holding onto the getter and all its

View on GitHub (pinned to 3366c21a63)

Solutions

1. Ensure every host in the connection string / seedlist is a non-empty `host:port` value.
2. Validate addresses with `HostAddress.fromString(addr)` before use and skip empties.
3. If surfaced from internal SDAM, update the driver and report it with the server hello response.

Example fix

// before
new ServerDescription('')
// after
new ServerDescription(HostAddress.fromString('localhost:27017'))

function assertHost(addr) {
  if (addr == null || addr === '') throw new TypeError('host must be non-empty');
  return typeof addr === 'string' ? HostAddress.fromString(addr) : addr;
}

function isNonEmptyHost(addr) {
  return typeof addr === 'string' ? addr.trim() !== '' : addr instanceof HostAddress;
}

When it happens

Trigger: Internally constructing a ServerDescription from an empty host string or null seed; a malformed seedlist entry; a hello/SDAM response that yields an empty host during topology updates.

Common situations: Passing a blank host in the connection string (`mongodb:///defaultauthdb`); a seedlist array containing an empty string; programmatic topology construction with an unparsed address.

Related errors

• Options for SrvPoller must exist and include srvHost
• No workflow provided to the OIDC auth provider.
• ConnectionPool.clear() called in load balanced mode with no
• Service generations are required in load balancer mode.
• Descriptors missing a type must define a transform

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