Automattic/mongoose · error · MongooseError

Model.findOneAndReplace() no longer accepts a callback

Error message

Model.findOneAndReplace() no longer accepts a callback

What it means

Mongoose 7 removed callback support from all Model and Query APIs; findOneAndReplace() returns a Query (thenable) only. The function throws this MongooseError synchronously if any of arguments[0] through arguments[3] is a function, covering filter, replacement, options, and the legacy trailing callback position.

Source

Thrown at lib/model.js:2644

 * @param {object} [options.lean] if truthy, mongoose will return the document as a plain JavaScript object rather than a mongoose document. See [`Query.lean()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.lean()) and [the Mongoose lean tutorial](https://mongoosejs.com/docs/tutorials/lean.html).
 * @param {ClientSession} [options.session=null] The session associated with this query. See [transactions docs](https://mongoosejs.com/docs/transactions.html).
 * @param {boolean|'throw'} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
 * @param {boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](https://mongoosejs.com/docs/guide.html#timestamps) are enabled, skip timestamps for this update. Note that this allows you to overwrite timestamps. Does nothing if schema-level timestamps are not set.
 * @param {object|string|string[]} [options.projection=null] optional fields to return, see [`Query.prototype.select()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.select())
 * @param {object|string} [options.sort] if multiple docs are found by the conditions, sets the sort order to choose which doc to update.
 * @param {boolean} [options.includeResultMetadata] if true, returns the full [ModifyResult from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/7.0/interfaces/ModifyResult.html) rather than just the document
 * @param {object|string} [options.select] sets the document fields to return.
 * @param {number} [options.maxTimeMS] puts a time limit on the query - requires mongodb >= 2.6.0
 * @param {boolean} [options.translateAliases=null] If set to `true`, translates any schema-defined aliases in `filter`, `projection`, `update`, and `distinct`. Throws an error if there are any conflicts where both alias and raw property are defined on the same object.
 * @return {Query}
 * @api public
 */

Model.findOneAndReplace = function(filter, replacement, options) {
  _checkContext(this, 'findOneAndReplace');

  if (typeof arguments[0] === 'function' || typeof arguments[1] === 'function' || typeof arguments[2] === 'function' || typeof arguments[3] === 'function') {
    throw new MongooseError('Model.findOneAndReplace() no longer accepts a callback');
  }

  let fields;
  if (options) {
    fields = options.select;
    options.select = undefined;
  }

  const mq = new this.Query({}, {}, this, this.$__collection);
  mq.select(fields);

  return mq.findOneAndReplace(filter, replacement, options);
};

/**
 * Shortcut for saving one or more documents to the database.
 * `MyModel.create(docs)` does `new MyModel(doc).save()` for every doc in
 * docs.

View on GitHub (pinned to 49cdab0136)

Solutions

  1. Replace the callback with await: const doc = await Model.findOneAndReplace(filter, replacement, { returnDocument: 'after' }); in try/catch
  2. Or use .then()/.catch() on the returned Query
  3. Grep and migrate all callback-based Model methods together (the Mongoose 6 to 7 migration guide lists them)
  4. Pin mongoose@6 temporarily if needed, then migrate
  5. Use TypeScript to catch removed overloads at compile time

Example fix

// before
User.findOneAndReplace({ _id }, { name: 'a' }, { new: true }, (err, doc) => { ... });

// after
const doc = await User.findOneAndReplace({ _id }, { name: 'a' }, { returnDocument: 'after' });
Defensive patterns

Strategy: validation

Validate before calling

function assertNoCallbacks(fnName, args) {
  const i = args.findIndex(a => typeof a === 'function');
  if (i !== -1) throw new TypeError(`${fnName}: callbacks removed in Mongoose 7; use await`);
}
// assertNoCallbacks('findOneAndReplace', [filter, replacement, options]);

Try / catch

try {
  const doc = await Model.findOneAndReplace(filter, replacement, { returnDocument: 'after' });
} catch (err) {
  if (/no longer accepts a callback/.test(err.message)) { /* migrate call site */ }
  else throw err;
}

Prevention

When it happens

Trigger: Calling Model.findOneAndReplace(filter, replacement, options, callback) or Model.findOneAndReplace(filter, replacement, callback) with pre-7 code. Also triggered when a function value ends up in the filter or replacement slot through argument misordering.

Common situations: Migrating from Mongoose 6 to 7/8; reusing callback-style snippets from old documentation or answers; wrapper functions that forward variadic arguments including callbacks.

Related errors

AI-assisted analysis of Automattic/mongoose@49cdab0136 (2026-08-21). Data as JSON: /api/errors/557b15d4a774d536. Report an issue: GitHub.