{"record":{"id":"c227c7abef230bfa","repo":"Automattic/mongoose","slug":"aggregate-prototype-explain-no-longer-accepts-a","errorCode":null,"errorMessage":"Aggregate.prototype.explain() no longer accepts a callback","messagePattern":"Aggregate\\.prototype\\.explain\\(\\) no longer accepts a callback","errorType":"exception","errorClass":"MongooseError","httpStatus":null,"severity":"warning","filePath":"lib/aggregate.js","lineNumber":799,"sourceCode":"  }\n\n  return this.append({ $redact: expression });\n};\n\n/**\n * Execute the aggregation with explain\n *\n * #### Example:\n *\n *     Model.aggregate(..).explain()\n *\n * @param {'queryPlanner'|'executionStats'|'allPlansExecution'} [verbosity]\n * @return {Promise}\n */\n\nAggregate.prototype.explain = async function explain(verbosity) {\n  if (typeof verbosity === 'function' || typeof arguments[1] === 'function') {\n    throw new MongooseError('Aggregate.prototype.explain() no longer accepts a callback');\n  }\n  const model = this._model;\n\n  if (!this._pipeline.length) {\n    throw new MongooseError('Aggregate has empty pipeline');\n  }\n\n  prepareDiscriminatorPipeline(this._pipeline, this._model.schema);\n\n  const preFilter = buildMiddlewareFilter(this.options, 'pre');\n  const postFilter = buildMiddlewareFilter(this.options, 'post');\n\n  // Remove middleware option before passing to MongoDB\n  const options = this.options != null ? { ...this.options } : {};\n  delete options.middleware;\n\n  try {\n    await model.hooks.execPre('aggregate', this, [], { filter: preFilter });","sourceCodeStart":781,"sourceCodeEnd":817,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/aggregate.js#L781-L817","documentation":"mongoose.set('returnOriginal', true|false) was the pre-6 way to control whether findOneAndUpdate returns the document before or after the update. It was replaced by returnDocument ('before'|'after'), and mongoose.set() now warns on every use. Setting is still applied for backwards compat, but Mongoose also hard-errors if you set returnOriginal after returnDocument (or vice versa) — the two options are mutually exclusive to prevent ambiguity.","triggerScenarios":"mongoose.set('returnOriginal', false) at app bootstrap; config files carried from Mongoose 4/5; setting both 'returnDocument' and 'returnOriginal' (which throws 'Cannot set ... when ... is already set' rather than warning).","commonSituations":"Apps upgraded across major Mongoose versions where the config line survived; shared config modules used by services on different Mongoose majors; tutorials copied from pre-2020 docs; CI failures after adding returnDocument while an old set('returnOriginal') still exists.","solutions":["Replace with the new option: mongoose.set('returnOriginal', false) -> mongoose.set('returnDocument', 'after'); true -> 'before'.","Delete any lingering returnOriginal line once returnDocument is set — mixing them throws immediately.","Prefer per-query options ({ returnDocument: 'after' }) over global config for clearer code.","Grep the codebase for 'returnOriginal' after upgrading to catch config files, not just call sites."],"exampleFix":"// before\nmongoose.set('returnOriginal', false);\n\n// after\nmongoose.set('returnDocument', 'after');","handlingStrategy":"validation","validationCode":"// central config module\nfunction setReturnDocument(mode) {\n  if (mode !== 'before' && mode !== 'after') throw new Error(\"mode must be 'before' or 'after'\");\n  mongoose.set('returnDocument', mode);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Grep for 'returnOriginal' whenever upgrading Mongoose majors and migrate to returnDocument.","Never set both returnOriginal and returnDocument — Mongoose throws on the combination.","Keep global query config in one bootstrap module so stale options are easy to spot."],"tags":["mongoose","deprecation","configuration","query-options","upgrade"],"backgroundTag":"deprecated-api-call","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}