mongodb/node-mongodb-native · error · MongoRuntimeError

ClientSession requires a ServerSessionPool

Error message

ClientSession requires a ServerSessionPool

What it means

The ClientSession constructor also requires a valid `ServerSessionPool` instance; if `sessionPool` is null or not `instanceof ServerSessionPool` it throws MongoRuntimeError. Like the client check this guards an internal constructor that application code never calls directly.

Solutions

1. Use `client.startSession()` so the driver supplies its own pool.
2. In tests, mock the session at the public boundary instead of the constructor.
3. Avoid importing `ServerSessionPool` from internal paths; it is `@internal` and its shape can change.

Example fix

// before
const session = new ClientSession(client, {}, {}, clientOptions);

// after
const session = client.startSession();

// Never construct ClientSession; let the driver wire its own ServerSessionPool.
const session = client.startSession();

When it happens

Trigger: Direct `new ClientSession(client, null, ...)` or passing a plain object/fake instead of a real ServerSessionPool; coupling tests to constructor internals.

Common situations: Unit-test fakes that substitute a hand-rolled pool object; forks of the driver; reflection-based construction.

Related errors

• ClientSession requires a MongoClient
• ServerSessionPool requires a MongoClient
• Argument "size" must be a non-negative number
• Cannot call abortTransaction after calling commitTransaction
• Cannot call abortTransaction twice

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

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