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

Thrown by the ServerDescription constructor (src/sdam/server_description.ts:103) as MongoRuntimeError when the address argument is null, undefined, or the empty string. ServerDescription is an internal type representing a server's address and hello metadata; it always requires a host:port. This error usually signals a malformed seed in the connection string or an internal topology misconfiguration.

Solutions

  1. Validate the connection string has a non-empty host before connecting.
  2. Log the constructed URI at startup to catch empty-host mistakes.
  3. If seen from internal code paths, report to driver maintainers.

Example fix

// before
const client = new MongoClient('mongodb:///test');
// after
const client = new MongoClient('mongodb://localhost:27017/test');
Defensive patterns

Strategy: validation

Validate before calling

function assertValidUri(uri) {
  const parsed = new URL(uri);
  if (!parsed.hostname && !parsed.host) throw new Error('connection string missing host');
}

Type guard

function isNonEmptyAddress(v): v is string {
  return typeof v === 'string' && v.trim().length > 0;
}

Try / catch

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoRuntimeError && /non-empty address/.test(e.message)) {
    // fix the connection string
  }
  throw e;
}

Prevention

When it happens

Trigger: A connection string with an empty host segment (e.g. mongodb:///dbname or mongodb://:27017), or internal topology code constructing a ServerDescription with an undefined address.

Common situations: Malformed URI in configuration/env vars, dynamic URI construction that drops the host, or a bug in seedlist parsing.

Related errors

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

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