{"record":{"id":"7b536f5cfd2df1ed","repo":"mongodb/node-mongodb-native","slug":"clientsession-requires-a-mongoclient","errorCode":null,"errorMessage":"ClientSession requires a MongoClient","messagePattern":"ClientSession requires a MongoClient","errorType":"exception","errorClass":"MongoRuntimeError","httpStatus":null,"severity":"error","filePath":"src/sessions.ts","lineNumber":168,"sourceCode":"   * Create a client session.\n   * @internal\n   * @param client - The current client\n   * @param sessionPool - The server session pool (Internal Class)\n   * @param options - Optional settings\n   * @param clientOptions - Optional settings provided when creating a MongoClient\n   */\n  constructor(\n    client: MongoClient,\n    sessionPool: ServerSessionPool,\n    options: ClientSessionOptions,\n    clientOptions: MongoOptions\n  ) {\n    super();\n    this.on('error', noop);\n\n    if (client == null) {\n      // TODO(NODE-3483)\n      throw new MongoRuntimeError('ClientSession requires a MongoClient');\n    }\n\n    if (sessionPool == null || !(sessionPool instanceof ServerSessionPool)) {\n      // TODO(NODE-3483)\n      throw new MongoRuntimeError('ClientSession requires a ServerSessionPool');\n    }\n\n    options = options ?? {};\n\n    this.snapshotEnabled = options.snapshot === true;\n    if (options.causalConsistency === true && this.snapshotEnabled) {\n      throw new MongoInvalidArgumentError(\n        'Properties \"causalConsistency\" and \"snapshot\" are mutually exclusive'\n      );\n    }\n\n    this.client = client;\n    this.sessionPool = sessionPool;","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/sessions.ts#L150-L186","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Stop constructing ClientSession directly; obtain one with `const session = await client.startSession()`.","If writing tests, mock at the `client.startSession` boundary, not the constructor.","Update any internal import paths to current package versions where the constructor signature changed.","If you genuinely need a session-like object in unit tests, build a minimal stub interface rather than reusing the real constructor."],"exampleFix":"// before\nconst session = new ClientSession(null, pool, {}, clientOptions);\n\n// after\nconst session = client.startSession();","handlingStrategy":"validation","validationCode":"// Always obtain sessions from the client; never construct ClientSession.\nfunction makeSession(client) {\n  if (client == null) throw new TypeError('client is required');\n  return client.startSession();\n}","typeGuard":"import { MongoClient } from 'mongodb';\nfunction isMongoClient(v) {\n  return v instanceof MongoClient;\n}","tryCatchPattern":null,"preventionTips":["Treat `ClientSession` constructor as off-limits; it is `@internal`.","Lint against importing `ClientSession` from internal package paths.","Obtain sessions exclusively through `client.startSession()`."],"tags":["sessions","internal","validation","misuse"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}