Automattic/mongoose · error · MongooseError

Please provide an executor function

Error message

Please provide an executor function

What it means

Connection.prototype.withSession(executor) borrows a MongoDB ClientSession, passes it to your function, and returns the function's result, handling session cleanup. It throws this error synchronously (surfacing as a rejected promise, since the method is async) when called with zero arguments, because there is no session work to do without an executor. It is a pure API-misuse guard, not a runtime condition.

Source

Thrown at lib/connection.js:658

/**
 * A convenience wrapper for `connection.client.withSession()`.
 *
 * #### Example:
 *
 *     await conn.withSession(async session => {
 *       const doc = await TestModel.findOne().session(session);
 *     });
 *
 * @method withSession
 * @param {Function} executor called with 1 argument: a `ClientSession` instance
 * @return {Promise} resolves to the return value of the executor function
 * @api public
 */

Connection.prototype.withSession = async function withSession(executor) {
  if (arguments.length === 0) {
    throw new MongooseError('Please provide an executor function');
  }
  return await this.client.withSession(executor);
};

/**
 * _Requires MongoDB >= 3.6.0._ Starts a [MongoDB session](https://www.mongodb.com/docs/manual/release-notes/3.6/#client-sessions)
 * for benefits like causal consistency, [retryable writes](https://www.mongodb.com/docs/manual/core/retryable-writes/),
 * and [transactions](https://thecodebarbarian.com/a-node-js-perspective-on-mongodb-4-transactions.html).
 *
 * #### Example:
 *
 *     const session = await conn.startSession();
 *     let doc = await Person.findOne({ name: 'Ned Stark' }, null, { session });
 *     await doc.deleteOne();
 *     // `doc` will always be null, even if reading from a replica set
 *     // secondary. Without causal consistency, it is possible to
 *     // get a doc back from the below query if the query reads from a
 *     // secondary that is experiencing replication lag.

View on GitHub (pinned to 49cdab0136)

Solutions

1. Pass an async executor: await conn.withSession(async session => { ... })
2. Guard optional executors before calling: if (typeof fn === 'function') await conn.withSession(fn)

Example fix

// before
await conn.withSession();

// after
await conn.withSession(async session => {
  await Model.findOne().session(session);
});

if (typeof executor !== 'function') {
  throw new TypeError('withSession requires an executor function');
}
await conn.withSession(executor);

const isExecutor = (v) => typeof v === 'function';

When it happens

Trigger: conn.withSession() with no argument, or conn.withSession(maybeFn) where the variable is undefined (e.g. a refactor removed the body but left the call).

Common situations: Skeleton code committed with the executor deleted; conditional executors that are only assigned on some code paths; optional session logic wired through a variable that is undefined in one branch.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid arguments
• Aggregate.prototype.exec() no longer accepts a callback
• Connection.prototype.startSession() no longer accepts a call
• `connection.model()` should not be run with `new`. If you ar
• The 2nd parameter to `mongoose.model()` should be a schema o

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