mongodb/node-mongodb-native · error · MongoRuntimeError

ClientSession requires a ServerSessionPool

Error message

ClientSession requires a ServerSessionPool

What it means

The `ClientSession` constructor requires `sessionPool` to be a `ServerSessionPool` instance (sessions.ts:171). The server session pool manages reusable server-side logical sessions; without it the client cannot acquire or return sessions. This is an internal invariant — `startSession()` always supplies a valid pool.

Source

Thrown at src/sessions.ts:173

   * @param clientOptions - Optional settings provided when creating a MongoClient
   */
  constructor(
    client: MongoClient,
    sessionPool: ServerSessionPool,
    options: ClientSessionOptions,
    clientOptions: MongoOptions
  ) {
    super();
    this.on('error', noop);

    if (client == null) {
      // TODO(NODE-3483)
      throw new MongoRuntimeError('ClientSession requires a MongoClient');
    }

    if (sessionPool == null || !(sessionPool instanceof ServerSessionPool)) {
      // TODO(NODE-3483)
      throw new MongoRuntimeError('ClientSession requires a ServerSessionPool');
    }

    options = options ?? {};

    this.snapshotEnabled = options.snapshot === true;
    if (options.causalConsistency === true && this.snapshotEnabled) {
      throw new MongoInvalidArgumentError(
        'Properties "causalConsistency" and "snapshot" are mutually exclusive'
      );
    }

    this.client = client;
    this.sessionPool = sessionPool;
    this.hasEnded = false;
    this.clientOptions = clientOptions;
    this.timeoutMS = options.defaultTimeoutMS ?? client.s.options?.timeoutMS;

    this.explicit = !!options.explicit;

View on GitHub (pinned to 3366c21a63)

Solutions

1. Obtain sessions via `client.startSession()` which provides the correct internal pool.
2. In tests, mock at the MongoClient level rather than replacing the session pool.
3. If writing internal tooling, source the pool from `client.s.sessionPool`.

Example fix

// before
const session = new ClientSession(client, {} as any, {});
// after
const session = client.startSession();

function isServerSessionPool(p) {
  return p instanceof ServerSessionPool;
}

When it happens

Trigger: Manually constructing ClientSession with a null or wrong-typed pool; passing a mock object that is not a ServerSessionPool; an internal wiring mistake.

Common situations: Test doubles that substitute the pool; refactors that bypass `client.startSession()`.

Related errors

• ClientSession requires a MongoClient
• Unexpected null serverSession for an explicit session
• ServerSessionPool requires a MongoClient
• Operation passed in cannot be an Array
• Operation passed in cannot be an Array

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/4a27a2873fd61995.json. Report an issue: GitHub.