mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Missing required callback parameter

Error message

Missing required callback parameter

What it means

Thrown by MongoClient.withSession() when no executor callback is supplied. The method's overloads require a callback that receives the ClientSession; without one there is nothing to run and the session lifecycle would be unmanageable. TypeScript normally forbids this at compile time, so a runtime hit means plain-JS callers or a malformed overload resolution.

Solutions

1. Pass a callback as the last argument: client.withSession(session => { ... }) or client.withSession({ ...options }, session => { ... }).
2. If writing plain JS, double-check argument positions against the TS overloads since the compiler will not guard you.
3. Consider using explicit startSession()/endSession() pairs if you cannot fit your control flow into a single callback.

Example fix

// before
await client.withSession({ causalConsistency: true });

// after
await client.withSession({ causalConsistency: true }, async session => {
  await collection.insertOne({}, { session });
});

// before calling withSession
function isWithSessionCallback(fn) {
  return typeof fn === 'function';
}
if (!isWithSessionCallback(maybeCb)) {
  throw new TypeError('withSession requires a callback');
}
await client.withSession(opts, maybeCb);

const isWithSessionCallback = (v: unknown): v is (session: import('mongodb').ClientSession) => unknown =>
  typeof v === 'function';

When it happens

Trigger: Calling client.withSession() with zero arguments, with only an options object and no callback, or with the callback passed as the wrong positional argument so the internal typeof check resolves to undefined.

Common situations: Plain JavaScript codebases bypassing the TypeScript overload checks; refactors that drop the callback while keeping options; accidentally awaiting withSession(session => ...) where the arrow is mis-indented and not actually passed.

Related errors

• Argument "docs" must be an array of documents
• Argument "operations" must be an array of documents
• Argument "pipeline" must be an array of aggregation stages
• ClientSession must be from the same MongoClient
• Use of expired sessions is not permitted

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/e084906f3da5af6f. Report an issue: GitHub.

Appendix: source

Thrown at src/mongo_client.ts:939

    options: ClientSessionOptions,
    executor: WithSessionCallback<T>
  ): Promise<T>;
  async withSession<T = any>(
    optionsOrExecutor: ClientSessionOptions | WithSessionCallback<T>,
    executor?: WithSessionCallback<T>
  ): Promise<T> {
    const options = {
      // Always define an owner
      owner: Symbol(),
      // If it's an object inherit the options
      ...(typeof optionsOrExecutor === 'object' ? optionsOrExecutor : {})
    };

    const withSessionCallback =
      typeof optionsOrExecutor === 'function' ? optionsOrExecutor : executor;

    if (withSessionCallback == null) {
      throw new MongoInvalidArgumentError('Missing required callback parameter');
    }

    const session = this.startSession(options);

    try {
      return await withSessionCallback(session);
    } finally {
      try {
        await session.endSession();
      } catch (error) {
        squashError(error);
      }
    }
  }

  /**
   * Create a new Change Stream, watching for new changes (insertions, updates,
   * replacements, deletions, and invalidations) in this cluster. Will ignore all

View on GitHub (pinned to dce7939f86)