{"record":{"id":"352a2a9ab730887a","repo":"mongodb/node-mongodb-native","slug":"service-generations-are-required-in-load-balancer","errorCode":null,"errorMessage":"Service generations are required in load balancer mode.","messagePattern":"Service generations are required in load balancer mode\\.","errorType":"exception","errorClass":"MongoRuntimeError","httpStatus":null,"severity":"error","filePath":"src/cmap/connection_pool.ts","lineNumber":435,"sourceCode":"  clear(options: { serviceId?: ObjectId; interruptInUseConnections?: boolean } = {}): void {\n    if (this.closed) {\n      return;\n    }\n\n    // handle load balanced case\n    if (this.loadBalanced) {\n      const { serviceId } = options;\n      if (!serviceId) {\n        throw new MongoRuntimeError(\n          'ConnectionPool.clear() called in load balanced mode with no serviceId.'\n        );\n      }\n      const sid = serviceId.toHexString();\n      const generation = this.serviceGenerations.get(sid);\n      // Only need to worry if the generation exists, since it should\n      // always be there but typescript needs the check.\n      if (generation == null) {\n        throw new MongoRuntimeError('Service generations are required in load balancer mode.');\n      } else {\n        // Increment the generation for the service id.\n        this.serviceGenerations.set(sid, generation + 1);\n      }\n      this.emitAndLog(\n        ConnectionPool.CONNECTION_POOL_CLEARED,\n        new ConnectionPoolClearedEvent(this, { serviceId })\n      );\n      return;\n    }\n    // handle non load-balanced case\n    const interruptInUseConnections = options.interruptInUseConnections ?? false;\n    const oldGeneration = this.generation;\n    this.generation += 1;\n    const alreadyPaused = this.poolState === PoolState.paused;\n    this.poolState = PoolState.paused;\n\n    this.clearMinPoolSizeTimer();","sourceCodeStart":417,"sourceCodeEnd":453,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/cmap/connection_pool.ts#L417-L453","documentation":"A MongoRuntimeError thrown in ConnectionPool.clear during load-balanced mode when a serviceId is provided but no generation entry exists for it in the serviceGenerations map. The map should be populated when connections are created for that service; a missing entry indicates the pool's bookkeeping is out of sync with the connections it holds. This is an internal invariant violation.","triggerScenarios":"A clear({ serviceId }) call in load-balanced mode before any connection for that serviceId has been established, or after the generation map was inadvertently reset. End users see this only via internal SDAM paths under load-balanced topologies.","commonSituations":"Driver bug in the load-balanced generation-tracking lifecycle; race between pool clear and connection establishment; SDAM reconfiguration under a load balancer where serviceIds appear/disappear rapidly.","solutions":["Upgrade the driver to the latest patch release (load-balanced generation handling has had fixes).","Verify the load balancer presents a stable set of backend serviceIds.","Report to the driver team if the error reproduces on the current release.","If load-balanced mode is not required, switch to replicaSet= or direct connection."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await operation();\n} catch (e) {\n  if (e instanceof MongoRuntimeError && /Service generations/.test(e.message)) {\n    // reconnect / recreate client; report if persistent\n  } else throw e;\n}","preventionTips":["Keep the driver on the latest patch release for load-balanced fixes.","Ensure stable backend serviceIds behind the load balancer.","Fall back to replicaSet= if load-balanced mode is not required."],"tags":["load-balanced","connection-pool","internal","sdam"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}