{"record":{"id":"1b2038b520f4ca74","repo":"Automattic/mongoose","slug":"connection-prototype-startsession-no-longer-acce","errorCode":null,"errorMessage":"Connection.prototype.startSession() no longer accepts a callback","messagePattern":"Connection\\.prototype\\.startSession\\(\\) no longer accepts a callback","errorType":"exception","errorClass":"MongooseError","httpStatus":null,"severity":"error","filePath":"lib/connection.js","lineNumber":689,"sourceCode":" *     let doc = await Person.findOne({ name: 'Ned Stark' }, null, { session });\n *     await doc.deleteOne();\n *     // `doc` will always be null, even if reading from a replica set\n *     // secondary. Without causal consistency, it is possible to\n *     // get a doc back from the below query if the query reads from a\n *     // secondary that is experiencing replication lag.\n *     doc = await Person.findOne({ name: 'Ned Stark' }, null, { session, readPreference: 'secondary' });\n *\n *\n * @method startSession\n * @param {object} [options] see the [mongodb driver options](https://mongodb.github.io/node-mongodb-native/7.0/classes/MongoClient.html#startSession)\n * @param {boolean} [options.causalConsistency=true] set to false to disable causal consistency\n * @return {Promise<ClientSession>} promise that resolves to a MongoDB driver `ClientSession`\n * @api public\n */\n\nConnection.prototype.startSession = async function startSession(options) {\n  if (arguments.length >= 2 && typeof arguments[1] === 'function') {\n    throw new MongooseError('Connection.prototype.startSession() no longer accepts a callback');\n  }\n\n  await this._waitForConnect();\n\n  const session = this.client.startSession(options);\n  return session;\n};\n\n/**\n * _Requires MongoDB >= 3.6.0._ Executes the wrapped async function\n * in a transaction. Mongoose will commit the transaction if the\n * async function executes successfully and attempt to retry if\n * there was a retriable error.\n *\n * Calls the MongoDB driver's [`session.withTransaction()`](https://mongodb.github.io/node-mongodb-native/7.0/classes/ClientSession.html#withTransaction),\n * but also handles resetting Mongoose document state as shown below.\n *\n * #### Example:","sourceCodeStart":671,"sourceCodeEnd":707,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/connection.js#L671-L707","documentation":"Mongoose 7 removed all callback-style APIs; startSession() is async and returns a Promise<ClientSession>. An explicit guard throws when a function is detected in the second argument position so legacy callback code fails loudly at the call site instead of the callback being silently ignored (arguments[1] would otherwise never run).","triggerScenarios":"conn.startSession({ causalConsistency: false }, (err, session) => { ... }) — an options object followed by a callback function (arguments.length >= 2 with arguments[1] a function).","commonSituations":"Upgrading a codebase from mongoose 6.x or earlier to 7/8/9; copying pre-promise-era tutorials or Stack Overflow answers; old transaction helpers written callback-style.","solutions":["Remove the callback and await: const session = await conn.startSession()","Move the old callback body into try/catch around awaited calls","When upgrading, grep the repo for startSession( calls taking two arguments"],"exampleFix":"// before\nconn.startSession({ causalConsistency: true }, (err, session) => { /* ... */ });\n\n// after\nconst session = await conn.startSession({ causalConsistency: true });","handlingStrategy":"validation","validationCode":"function startSessionSafe(options) {\n  if (typeof options === 'function') {\n    throw new TypeError('callback passed to promise-only startSession');\n  }\n  return conn.startSession(options);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["No Mongoose 7+ API accepts callbacks — always await the returned promise","When upgrading, grep for method calls whose last argument is a function","Use TypeScript so callback signatures mismatch the typed declarations at compile time"],"tags":["session","callbacks","migration","mongoose-7"],"backgroundTag":"callback-api-removed","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}