mongodb/node-mongodb-native · error · MongoRuntimeError

ClientSession requires a MongoClient

Error message

ClientSession requires a MongoClient

What it means

The ClientSession constructor (marked `@internal`) requires a MongoClient; if `client == null` it throws MongoRuntimeError. Application code obtains sessions via `client.startSession()`, which always supplies the client, so reaching this error means the internal constructor is being called directly without a client.

Solutions

1. Stop constructing ClientSession directly; obtain one with `const session = await client.startSession()`.
2. If writing tests, mock at the `client.startSession` boundary, not the constructor.
3. Update any internal import paths to current package versions where the constructor signature changed.
4. If you genuinely need a session-like object in unit tests, build a minimal stub interface rather than reusing the real constructor.

Example fix

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

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

// Always obtain sessions from the client; never construct ClientSession.
function makeSession(client) {
  if (client == null) throw new TypeError('client is required');
  return client.startSession();
}

import { MongoClient } from 'mongodb';
function isMongoClient(v) {
  return v instanceof MongoClient;
}

When it happens

Trigger: Direct `new ClientSession(null, pool, options, clientOptions)`; reflection/mocks that bypass `startSession`; test doubles that pass `undefined` for the client; misuse of internal symbols pulled from the package's internal tree.

Common situations: A test stub or monkeypatch that constructs ClientSession manually; an outdated fork of the driver; library code that re-exports internals and calls them with wrong arity.

Related errors

• ClientSession requires a ServerSessionPool
• 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/7b536f5cfd2df1ed. Report an issue: GitHub.

Appendix: source

Thrown at src/sessions.ts:168

   * Create a client session.
   * @internal
   * @param client - The current client
   * @param sessionPool - The server session pool (Internal Class)
   * @param options - Optional settings
   * @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;

View on GitHub (pinned to dce7939f86)