mongodb/node-mongodb-native · error · MongoRuntimeError

ServerSessionPool requires a MongoClient

Error message

ServerSessionPool requires a MongoClient

What it means

Thrown by the ServerSessionPool constructor when the client argument is null or undefined. ServerSessionPool is an @internal class used by the driver to manage logical server sessions; users do not construct it directly. The guard prevents the driver from later dereferencing a null topology. It is a MongoRuntimeError.

Source

Thrown at src/sessions.ts:1093

      ((calculateDurationInMs(this.lastUse) % 86400000) % 3600000) / 60000
    );

    return idleTimeMinutes > sessionTimeoutMinutes - 1;
  }
}

/**
 * Maintains a pool of Server Sessions.
 * For internal use only
 * @internal
 */
export class ServerSessionPool {
  client: MongoClient;
  sessions: List<ServerSession>;

  constructor(client: MongoClient) {
    if (client == null) {
      throw new MongoRuntimeError('ServerSessionPool requires a MongoClient');
    }

    this.client = client;
    this.sessions = new List<ServerSession>();
  }

  /**
   * Acquire a Server Session from the pool.
   * Iterates through each session in the pool, removing any stale sessions
   * along the way. The first non-stale session found is removed from the
   * pool and returned. If no non-stale session is found, a new ServerSession is created.
   */
  acquire(): ServerSession {
    const sessionTimeoutMinutes = this.client.topology?.logicalSessionTimeoutMinutes ?? 10;

    let session: ServerSession | null = null;

    // Try to obtain from session pool

View on GitHub (pinned to 3366c21a63)

Solutions

1. Do not construct ServerSessionPool yourself; obtain sessions via client.startSession() which uses the client's internal pool.
2. If writing driver internals/tests, pass a fully-constructed MongoClient instance to the constructor.
3. Ensure the MongoClient has finished connecting/topology init before the pool is accessed.

Example fix

// before (internal/test code)
const pool = new ServerSessionPool(undefined); // throws

// after
const client = new MongoClient(uri);
await client.connect();
const pool = new ServerSessionPool(client);

// internal only - do not construct ServerSessionPool directly
if (client != null) {
  const pool = new ServerSessionPool(client);
}
// users: just call client.startSession()

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

When it happens

Trigger: Internally constructing new ServerSessionPool(undefined) or new ServerSessionPool(null); reaching the constructor via a test stub or subclass that passes no client; a MongoClient that failed to fully initialize before the pool was built.

Common situations: Driver-internal bugs; unit tests that instantiate ServerSessionPool without a real client; custom MongoClient subclasses or mocks that break the expected initialization order.

Related errors

• Unexpected HostAddress ${JSON.stringify(hostAddress)}
• An unexpected error type: ${typeof error}
• ClientSession requires a MongoClient
• ClientSession requires a ServerSessionPool
• Unexpected null serverSession for an explicit session

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