mongodb/node-mongodb-native · error · MongoRuntimeError

Service generations are required in load balancer mode.

Error message

Service generations are required in load balancer mode.

What it means

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.

Solutions

1. Upgrade the driver to the latest patch release (load-balanced generation handling has had fixes).
2. Verify the load balancer presents a stable set of backend serviceIds.
3. Report to the driver team if the error reproduces on the current release.
4. If load-balanced mode is not required, switch to replicaSet= or direct connection.

try {
  await operation();
} catch (e) {
  if (e instanceof MongoRuntimeError && /Service generations/.test(e.message)) {
    // reconnect / recreate client; report if persistent
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• ConnectionPool.clear() called in load balanced mode with no…
• Argument "setName" is required if connected to a replica set
• illegal state transition from
• Limit must be less than the number of items
• A collection name must be determined before getMore

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

Appendix: source

Thrown at src/cmap/connection_pool.ts:435

  clear(options: { serviceId?: ObjectId; interruptInUseConnections?: boolean } = {}): void {
    if (this.closed) {
      return;
    }

    // handle load balanced case
    if (this.loadBalanced) {
      const { serviceId } = options;
      if (!serviceId) {
        throw new MongoRuntimeError(
          'ConnectionPool.clear() called in load balanced mode with no serviceId.'
        );
      }
      const sid = serviceId.toHexString();
      const generation = this.serviceGenerations.get(sid);
      // Only need to worry if the generation exists, since it should
      // always be there but typescript needs the check.
      if (generation == null) {
        throw new MongoRuntimeError('Service generations are required in load balancer mode.');
      } else {
        // Increment the generation for the service id.
        this.serviceGenerations.set(sid, generation + 1);
      }
      this.emitAndLog(
        ConnectionPool.CONNECTION_POOL_CLEARED,
        new ConnectionPoolClearedEvent(this, { serviceId })
      );
      return;
    }
    // handle non load-balanced case
    const interruptInUseConnections = options.interruptInUseConnections ?? false;
    const oldGeneration = this.generation;
    this.generation += 1;
    const alreadyPaused = this.poolState === PoolState.paused;
    this.poolState = PoolState.paused;

    this.clearMinPoolSizeTimer();

View on GitHub (pinned to dce7939f86)