Automattic/mongoose · error · MongooseError

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

Error message

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

What it means

destroy() permanently closes the connection — like close(), but it also removes the connection from mongoose's connections list and prevents reopening. Mongoose 7 removed callbacks, and any function argument (as force, or as a second argument after force) is rejected immediately. Note that an object as force (e.g. { force: true }) is still valid; only functions throw.

Source

Thrown at lib/connection.js:1193

    err = new ServerSelectionError();
    err.assimilateError(originalError);
  }

  return err;
}

/**
 * Destroy the connection. Similar to [`.close`](https://mongoosejs.com/docs/api/connection.html#Connection.prototype.close()),
 * but also removes the connection from Mongoose's `connections` list and prevents the
 * connection from ever being re-opened.
 *
 * @param {boolean} [force]
 * @returns {Promise}
 */

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

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

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

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

View on GitHub (pinned to 49cdab0136)

Solutions

Remove the callback and await: await conn.destroy()
In shutdown handlers: server.close(async () => { await conn.destroy(); })

Example fix

// before
conn.destroy(true, (err) => { process.exit(0); });

// after
await conn.destroy(true);
process.exit(0);

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

In shutdown handlers, await conn.destroy() inside the async handler
Remember destroy(force) also accepts { force: true } — objects are fine, functions are not
Test shutdown paths (SIGTERM) so migration breakage surfaces in CI, not production

When it happens

Trigger: conn.destroy(() => { ... }) or conn.destroy(true, (err) => { ... }).

Common situations: Graceful-shutdown handlers (SIGTERM/SIGINT) written callback-style in older codebases; migration to mongoose 7/8/9.

Related errors

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