mongodb/node-mongodb-native · error · MongoRuntimeError

ConnectionPool.clear() called in load balanced mode with no

Error message

ConnectionPool.clear() called in load balanced mode with no serviceId.

What it means

Thrown by ConnectionPool.clear() when the pool is in load-balanced mode (loadBalanced=true) but no serviceId was supplied. In load-balanced topology the driver tracks a separate generation per service (mongos) id, so clearing the pool must identify which service's connections to invalidate. The absence of a serviceId is an internal-driver invariant violation, not something a typical application triggers directly. It surfaces as a MongoRuntimeError during SDAM pool-clear handling (e.g. after a network error or pool staleness event).

Source

Thrown at src/cmap/connection_pool.ts:426

    queueMicrotask(() => this.processWaitQueue());
  }

  /**
   * Clear the pool
   *
   * Pool reset is handled by incrementing the pool's generation count. Any existing connection of a
   * previous generation will eventually be pruned during subsequent checkouts.
   */
  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;

View on GitHub (pinned to 3366c21a63)

Solutions

1. Ensure you are on a current driver patch version; if serviceId propagation is broken it is a driver bug that is fixed in releases, so upgrade `mongodb` and retry.
2. Verify the deployment is genuinely a load-balanced topology (mongos behind an L4 LB) and that the connection string uses loadBalanced=true only in that case; mismatched topology + flag can confuse SDAM.
3. If you have custom SDAM instrumentation or a proxy that intercepts clear(), make sure it forwards the serviceId option from ConnectionPoolClearedEvent / server description.
4. If reproducible, file a driver bug with the connection string (redacted), driver version, server version, and SDAM logging enabled (MONGODB_LOGGING=debug).

Example fix

// before (incorrect topology flag for a replica set)
const client = new MongoClient(uri, { loadBalanced: true }); // wrong for RS

// after - only use loadBalanced behind an L4 LB fronting mongos
const client = new MongoClient(uri); // RS/standalone: omit the flag

// This is an internal driver invariant in load-balanced mode; callers cannot validate it.
// Wrap pool-sensitive operations and recycle the client on a persistent MongoRuntimeError.
try {
  await collection.findOne(filter);
} catch (err) {
  if (err instanceof MongoRuntimeError && /load balanced mode with no serviceId/.test(err.message)) {
    // recycle client to reset SDAM/pool state
    await client.close();
    client = new MongoClient(uri, { loadBalanced: true });
  }
  throw err;
}

When it happens

Trigger: The driver's SDAM layer calls pool.clear({ serviceId }) after events like a network error, server description change, or staleness in a load-balanced deployment. If the code path that invokes clear() omits serviceId while loadBalanced is true, this throws. This is almost exclusively hit when connecting with loadBalanced: true against a load balancer fronting mongos instances, and an internal call site fails to propagate the serviceId from the server's hello response.

Common situations: Using the driver behind a Layer-4 load balancer (loadBalanced: true in MongoClientOptions) where the server hello's serviceId was not captured or was dropped by a custom SDAM integration. Encountered after upgrading the driver across versions that changed how serviceId is threaded through clear().-proxy or connection-pool instrumentation that wraps or replaces pool.clear() without forwarding serviceId. Never seen on replica set or standalone topologies.

Related errors

• Service generations are required in load balancer mode.
• 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/7d1fc1f639ca5ef5.json. Report an issue: GitHub.