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

Thrown by `updateRsWithPrimaryFromMember` during SDAM topology updates when `setName` is null while processing a replica-set member hello (topology_description.ts:500). The driver reached a code path that requires a setName because it believes the topology is a replica set, but no setName was configured. This is treated as a runtime/driver-internal error.

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

Solutions

1. Add the `replicaSet=<name>` option to your connection string when targeting a replica set.
2. Update to the latest driver patch release; if it recurs with a correct URI, report a bug with the hello response.

Example fix

// before
new MongoClient('mongodb://host1,host2,host3/db');
// after
new MongoClient('mongodb://host1,host2,host3/db?replicaSet=myRs');

function assertRsUri(uri, setName) {
  if (setName && !/replicaSet=/.test(uri)) {
    return uri + (uri.includes('?') ? '&' : '?') + 'replicaSet=' + setName;
  }
  return uri;
}

function hasReplicaSetOption(uri) {
  return /[?&]replicaSet=/.test(uri);
}

When it happens

Trigger: Connecting to a replica set without setting `replicaSet`/`directConnection` correctly while the SDAM logics still classifies the topology as a replica set; an internal call passing null setName.

Common situations: Connection string omits `replicaSet=name`; a single-node deployment misdetected as a replica set; driver version mismatch with server SDAM response shape.

Related errors

• ConnectionPool.clear() called in load balanced mode with no
• Service generations are required in load balancer mode.
• ServerDescription must be provided with a non-empty address
• unexpected topology type: ${topologyDescription.type} (this
• Options for SrvPoller must exist and include srvHost

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