{"id":"ea116dc6595f5a4c","repo":"mongodb/node-mongodb-native","slug":"unexpected-null-serversession-for-an-explicit-sess","errorCode":null,"errorMessage":"Unexpected null serverSession for an explicit session","messagePattern":"Unexpected null serverSession for an explicit session","errorType":"exception","errorClass":"MongoRuntimeError","httpStatus":null,"severity":"error","filePath":"src/sessions.ts","lineNumber":218,"sourceCode":"\n    this.clusterTime = options.initialClusterTime;\n\n    this.operationTime = undefined;\n    this.owner = options.owner;\n    this.defaultTransactionOptions = { ...options.defaultTransactionOptions };\n    this.transaction = new Transaction();\n  }\n\n  /** The server id associated with this session */\n  get id(): ServerSessionId | undefined {\n    return this.serverSession?.id;\n  }\n\n  get serverSession(): ServerSession {\n    let serverSession = this._serverSession;\n    if (serverSession == null) {\n      if (this.explicit) {\n        throw new MongoRuntimeError('Unexpected null serverSession for an explicit session');\n      }\n      if (this.hasEnded) {\n        throw new MongoRuntimeError('Unexpected null serverSession for an ended implicit session');\n      }\n      serverSession = this.sessionPool.acquire();\n      this._serverSession = serverSession;\n    }\n    return serverSession;\n  }\n\n  get loadBalanced(): boolean {\n    return this.client.topology?.description.type === TopologyType.LoadBalanced;\n  }\n\n  /** @internal */\n  pin(conn: Connection): void {\n    if (this.pinnedConnection) {\n      throw TypeError('Cannot pin multiple connections to the same session');","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/sessions.ts#L200-L236","documentation":"Thrown by the `serverSession` getter when a session flagged `explicit` has no underlying `_serverSession` (sessions.ts:217). Explicit sessions acquire a server session eagerly at construction; a null value here indicates internal state corruption. It should not occur under correct usage.","triggerScenarios":"An explicit session whose `_serverSession` was nulled out prematurely; reuse of a session after internal cleanup; a driver bug in session acquisition/release.","commonSituations":"Driver internal lifecycle bug; concurrent disposal and use of an explicit session; an outdated driver version with a known session-pool regression.","solutions":["Update to the latest driver release.","Avoid sharing or reusing a session across concurrent disposal paths.","If it recurs, report a bug with the session lifecycle steps and driver version."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await session.withTransaction(async () => { /* ... */ });\n} catch (e) {\n  if (e instanceof MongoRuntimeError && /null serverSession for an explicit session/.test(e.message)) {\n    session = client.startSession(); // recreate the explicit session\n    return retry();\n  }\n  throw e;\n}","preventionTips":["Keep the driver up to date.","Avoid concurrent use and disposal of an explicit session.","Report persistent occurrences with the session lifecycle."],"tags":["sessions","internal","bug"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}