Automattic/mongoose · error · MongooseError

Connection.prototype.close() no longer accepts a callback

Error message

Connection.prototype.close() no longer accepts a callback

What it means

close() gracefully closes the connection and is async in Mongoose 7+; all callback-style APIs were removed. Any function argument — as force, or as a second argument after force — trips the guard so legacy code fails loudly instead of the callback never running. An object as force ({ force: true }) remains supported; only functions throw.

Source

Thrown at lib/connection.js:1215

    this.$wasForceClosed = !!force.force;
  } else {
    this.$wasForceClosed = !!force;
  }

  return this._close(force, true);
};

/**
 * Closes the connection
 *
 * @param {boolean} [force] optional
 * @return {Promise}
 * @api public
 */

Connection.prototype.close = async function close(force) {
  if (typeof force === 'function' || (arguments.length === 2 && typeof arguments[1] === 'function')) {
    throw new MongooseError('Connection.prototype.close() no longer accepts a callback');
  }

  if (force != null && typeof force === 'object') {
    this.$wasForceClosed = !!force.force;
  } else {
    this.$wasForceClosed = !!force;
  }

  if (this._lastHeartbeatAt != null) {
    this._lastHeartbeatAt = null;
  }

  for (const model of Object.values(this.models)) {
    // If manually disconnecting, make sure to clear each model's `$init`
    // promise, so Mongoose knows to re-run `init()` in case the
    // connection is re-opened. See gh-12047.
    delete model.$init;
  }

View on GitHub (pinned to 49cdab0136)

Solutions

Remove the callback and await: await conn.close()
In test hooks: afterAll(async () => { await conn.close(); })

Example fix

// before
conn.close((err) => { done(); });

// after
await conn.close();

Defensive patterns

Strategy: validation

Validate before calling

function closeSafe(...args) {
  if (args.some(a => typeof a === 'function')) {
    throw new TypeError('close takes no callback — await the promise');
  }
  return conn.close(...args);
}

Prevention

Write teardown as afterAll(async () => { await conn.close(); })
Pass { force: true } as an object when forced close is needed
Grep test helpers for close(done) patterns when upgrading mongoose majors

When it happens

Trigger: conn.close(() => { ... }) or conn.close(false, (err) => { ... }).

Common situations: afterAll/afterEach teardown in old test suites; shutdown hooks written against mongoose 6 or earlier.

Related errors

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