mongodb/node-mongodb-native · error · MongoRuntimeError

ClientSession requires a MongoClient

Error message

ClientSession requires a MongoClient

What it means

The `ClientSession` constructor requires a non-null MongoClient (sessions.ts:167). ClientSession is an `@internal`-ish construct; application code should obtain sessions exclusively through `client.startSession()`, which guarantees a client is present.

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 3366c21a63)

Solutions

1. Always create sessions with `const session = client.startSession(options)`.
2. In tests, use a real (possibly in-memory/mocked) MongoClient rather than constructing ClientSession directly.
3. Do not subclass or re-wrap ClientSession without forwarding the client.

Example fix

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

function startSession(client, options) {
  if (!client) throw new TypeError('ClientSession requires a MongoClient');
  return client.startSession(options);
}

function isMongoClient(c) {
  return c != null && typeof c.startSession === 'function';
}

When it happens

Trigger: Directly instantiating `new ClientSession(undefined, pool, ...)`; a custom subclass or test double that drops the client argument; an internal refactor passing null.

Common situations: Attempting to construct sessions manually instead of via the client; unit tests that stub ClientSession without a real client.

Related errors

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