{"record":{"id":"22e4441253a6bd52","repo":"mongodb/node-mongodb-native","slug":"argument-setname-is-required-if-connected-to-a-r","errorCode":null,"errorMessage":"Argument \"setName\" is required if connected to a replica set","messagePattern":"Argument \"setName\" is required if connected to a replica set","errorType":"exception","errorClass":"MongoRuntimeError","httpStatus":null,"severity":"error","filePath":"src/sdam/topology_description.ts","lineNumber":502,"sourceCode":"  const currentAddresses = Array.from(serverDescriptions.keys());\n  const responseAddresses = serverDescription.allHosts;\n  currentAddresses\n    .filter((addr: string) => responseAddresses.indexOf(addr) === -1)\n    .forEach((address: string) => {\n      serverDescriptions.delete(address);\n    });\n\n  return [checkHasPrimary(serverDescriptions), setName, maxSetVersion, maxElectionId];\n}\n\nfunction updateRsWithPrimaryFromMember(\n  serverDescriptions: Map<string, ServerDescription>,\n  serverDescription: ServerDescription,\n  setName: string | null = null\n): TopologyType {\n  if (setName == null) {\n    // TODO(NODE-3483): should be an appropriate runtime error\n    throw new MongoRuntimeError('Argument \"setName\" is required if connected to a replica set');\n  }\n\n  if (\n    setName !== serverDescription.setName ||\n    (serverDescription.me && serverDescription.address !== serverDescription.me)\n  ) {\n    serverDescriptions.delete(serverDescription.address);\n  }\n\n  return checkHasPrimary(serverDescriptions);\n}\n\nfunction updateRsNoPrimaryFromMember(\n  serverDescriptions: Map<string, ServerDescription>,\n  serverDescription: ServerDescription,\n  setName: string | null = null\n): [TopologyType, string | null] {\n  const topologyType = TopologyType.ReplicaSetNoPrimary;","sourceCodeStart":484,"sourceCodeEnd":520,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/sdam/topology_description.ts#L484-L520","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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.","solutions":["Check server logs and `rs.status()` for an in-progress reconfig or election; the error usually clears once topology settles.","Ensure every replica-set member reports the same `setName` and that no member is misconfigured with a blank set name.","Upgrade mongod and the driver to current patch levels if the error persists, then file a driver bug with DEBUG SDAM logs.","If behind a proxy (HAProxy, ngrok, etc.), remove it for a direct connection test to rule out hello-response rewriting."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await client.db('app').collection('c').findOne({});\n} catch (err) {\n  if (err.name === 'MongoRuntimeError' && err.message.includes('setName')) {\n    // topology state is inconsistent; reconnect after topology settles\n    logger.error('SDAM setName invariant hit', { err });\n    await waitAndReconnect(client);\n    return;\n  }\n  throw err;\n}","preventionTips":["Keep mongod versions consistent across the replica set during rolling upgrades.","Avoid proxies/load balancers that rewrite hello responses in production paths.","Enable SDAM DEBUG logging when investigating.","File a driver bug with reproducible logs if the error recurs in steady state."],"tags":["sdam","replica-set","internal","topology"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}