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

A MongoRuntimeError thrown in ConnectionPool.clear when the pool is in load-balanced mode and clear() is called without a serviceId. In load-balanced deployments the pool tracks per-service generations, so clearing requires identifying which backend service to reset. Omitting serviceId is an internal-driver error: the SDAM layer should always pass it on pool clear.

Solutions

1. Verify the deployment genuinely supports load-balanced mode (mongos behind a LB).
2. Ensure the driver version supports the load-balanced spec fully (4.x+).
3. Check that hello responses include the serviceId field (server 5.x+ behind a LB).
4. If not using load balancing, remove loadBalancer=true from the connection string.

Example fix

// before
const client = new MongoClient('mongodb://lb-host:27017/?loadBalancer=true');

// after (ensure LB front-ends mongos with serviceId; or drop the flag)
const client = new MongoClient('mongodb://rs-host:27017/?replicaSet=rs0');

// Only use loadBalancer=true with a deployment that advertises serviceId
if (uri.includes('loadBalancer=true')) {
  // ensure the endpoint is a mongos behind an L4 LB; otherwise remove the flag
}

When it happens

Trigger: Internal call path where ConnectionPool.clear({ serviceId }) is invoked in loadBalanced mode but serviceId is undefined. For end users this surfaces when using loadBalancer=true and the driver's internal clear logic loses track of the service id — typically after a hello/sdam error that prevents serviceId capture.

Common situations: Misconfigured load-balanced deployment (loadBalancer=true against a non-load-balanced endpoint); SDAM failing to capture the serviceId from a malformed server hello; driver version bugs in the load-balanced clear path; a proxy that strips the serviceId field from hello responses.

Related errors

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

Appendix: 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 dce7939f86)