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

Thrown in load-balancer mode after a valid serviceId is supplied to ConnectionPool.clear(), but no generation counter is registered for that service id in the pool's serviceGenerations map. The pool keeps a per-service generation number to invalidate stale connections; finding none means the service was never registered (or was deregistered) before a clear was attempted. This is an internal driver-state inconsistency surfaced as MongoRuntimeError. It indicates the pool's bookkeeping and SDAM's view of available services have diverged.

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

Solutions

1. Upgrade to the latest driver patch; service-generation registration races are fixed in driver releases, so bumping `mongodb` is the first action.
2. Confirm the load balancer presents a stable set of mongos backends and that service ids from hello are consistent; flapping backends cause registration divergence.
3. Restart the MongoClient to reset pool state if the error appears once after an infrastructure change and does not recur.
4. Report a driver bug with SDAM debug logs if it reproduces on the current version against a stable LB/mongos setup.

// Internal state inconsistency; recycle the client if it persists.
try {
  await db.command({ ping: 1 });
} catch (err) {
  if (err instanceof MongoRuntimeError && /Service generations are required/.test(err.message)) {
    await client.close();
    client = new MongoClient(uri, { loadBalanced: true });
    await client.connect();
  }
  throw err;
}

When it happens

Trigger: pool.clear({ serviceId }) is called with a serviceId that the pool has never seen (serviceGenerations.has(sid) === false). Happens if a server description's serviceId differs from what was recorded at connection/hello time, e.g. the load balancer rotated to a backend whose serviceId was not yet registered, or the pool was cleared for a stale/unknown service after a topology change. Internal call path, not user-invoked.

Common situations: Load-balanced deployments where the set of backing mongos service ids changes (autoscaling, LB reconfiguration) faster than the driver registers them. Driver version skew after upgrading across a release that changed service-generation registration timing. Custom monitoring that synthesizes clear() calls with fabricated service ids.

Related errors

• ConnectionPool.clear() called in load balanced mode with no
• No auth context found on connection.
• 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/352a2a9ab730887a.json. Report an issue: GitHub.