mongodb/node-mongodb-native · error · MongoRuntimeError

Argument "setName" is required if connected to a replica set

Error message

Argument "setName" is required if connected to a replica set

What it means

An internal SDAM invariant in `updateRsWithPrimaryFromMember` (topology_description.ts:500): the topology is processing a replica-set member's hello/heartbeat response but the cached `setName` is null. The driver cannot reconcile the member with the set without a name, so it throws MongoRuntimeError. This is a defensive check (the source even carries a TODO(NODE-3483) noting the error type is provisional) and normally indicates stale or inconsistent topology state rather than user misuse.

Solutions

1. Check server logs and `rs.status()` for an in-progress reconfig or election; the error usually clears once topology settles.
2. Ensure every replica-set member reports the same `setName` and that no member is misconfigured with a blank set name.
3. Upgrade mongod and the driver to current patch levels if the error persists, then file a driver bug with DEBUG SDAM logs.
4. If behind a proxy (HAProxy, ngrok, etc.), remove it for a direct connection test to rule out hello-response rewriting.

try {
  await client.db('app').collection('c').findOne({});
} catch (err) {
  if (err.name === 'MongoRuntimeError' && err.message.includes('setName')) {
    // topology state is inconsistent; reconnect after topology settles
    logger.error('SDAM setName invariant hit', { err });
    await waitAndReconnect(client);
    return;
  }
  throw err;
}

When it happens

Trigger: Driver-internal: the SDAM state machine receives an `updateRsWithPrimaryFromMember` transition while the tracked `setName` has not yet been populated. Surfaces during rapid topology changes — primary stepdown, reconfig, mixed-version replica set, or a buggy/misbehaving mongod `hello` response omitting `setName`.

Common situations: Connecting to a deployment that is mid-reconfig or rolling upgrade; an intermediate proxy/load balancer rewriting hello responses; a custom test harness that injects malformed server descriptions. End users almost never trigger it through the public API.

Related errors

• Cannot use srvMaxHosts option with replicaSet
• ConnectionPool.clear() called in load balanced mode with no…
• illegal state transition from
• Limit must be less than the number of items
• loadBalanced option not supported with a replicaSet option

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

Appendix: source

Thrown at src/sdam/topology_description.ts:502

  const currentAddresses = Array.from(serverDescriptions.keys());
  const responseAddresses = serverDescription.allHosts;
  currentAddresses
    .filter((addr: string) => responseAddresses.indexOf(addr) === -1)
    .forEach((address: string) => {
      serverDescriptions.delete(address);
    });

  return [checkHasPrimary(serverDescriptions), setName, maxSetVersion, maxElectionId];
}

function updateRsWithPrimaryFromMember(
  serverDescriptions: Map<string, ServerDescription>,
  serverDescription: ServerDescription,
  setName: string | null = null
): TopologyType {
  if (setName == null) {
    // TODO(NODE-3483): should be an appropriate runtime error
    throw new MongoRuntimeError('Argument "setName" is required if connected to a replica set');
  }

  if (
    setName !== serverDescription.setName ||
    (serverDescription.me && serverDescription.address !== serverDescription.me)
  ) {
    serverDescriptions.delete(serverDescription.address);
  }

  return checkHasPrimary(serverDescriptions);
}

function updateRsNoPrimaryFromMember(
  serverDescriptions: Map<string, ServerDescription>,
  serverDescription: ServerDescription,
  setName: string | null = null
): [TopologyType, string | null] {
  const topologyType = TopologyType.ReplicaSetNoPrimary;

View on GitHub (pinned to dce7939f86)