Automattic/mongoose · error · MongooseError

Connection#setClient not implemented by driver

Error message

Connection#setClient not implemented by driver

What it means

setClient() attaches an existing connected MongoDB driver MongoClient to a Mongoose connection (the documented flow: mongoose.createConnection().setClient(client)). Only the bundled node-mongodb-native driver implements it; the base class version (lib/connection.js:1736) just throws. Hitting it means the connection object is not the standard native-driver connection — a custom driver subclass or mock that never overrode setClient().

Source

Thrown at lib/connection.js:1736

 * that this connection uses to talk to MongoDB. This is useful if you already have a MongoClient instance, and want to
 * reuse it.
 *
 * #### Example:
 *
 *     const client = await mongodb.MongoClient.connect('mongodb://127.0.0.1:27017/test');
 *
 *     const conn = mongoose.createConnection().setClient(client);
 *
 *     conn.getClient(); // MongoClient { ... }
 *     conn.readyState; // 1, means 'CONNECTED'
 *
 * @api public
 * @param {MongClient} client The Client to set to be used.
 * @return {Connection} this
 */

Connection.prototype.setClient = function setClient() {
  throw new MongooseError('Connection#setClient not implemented by driver');
};

/*!
 * Called internally by `openUri()` to create a MongoClient instance.
 */

Connection.prototype.createClient = function createClient() {
  throw new MongooseError('Connection#createClient not implemented by driver');
};

/**
 * Syncs all the indexes for the models registered with this connection.
 *
 * @param {object} [options]
 * @param {boolean} [options.continueOnError] `false` by default. If set to `true`, mongoose will not throw an error if one model syncing failed, and will return an object where the keys are the names of the models, and the values are the results/errors for each model.
 * @return {Promise<object>} Returns a Promise, when the Promise resolves the value is a list of the dropped indexes.
 */
Connection.prototype.syncIndexes = async function syncIndexes(options = {}) {

View on GitHub (pinned to 49cdab0136)

Solutions

  1. Create the connection through the factory first: const conn = mongoose.createConnection(); await conn.setClient(client)
  2. Implement setClient(client) on your custom connection class (store the client and mark readyState connected)
  3. Alternatively skip Mongoose and use the driver client directly

Example fix

// before
const conn = new Connection(); // base class or subclass lacking setClient
conn.setClient(client); // throws

// after
const conn = mongoose.createConnection();
await conn.setClient(client);
Defensive patterns

Strategy: try-catch

Try / catch

try {
  await conn.setClient(client);
} catch (err) {
  if (/setClient not implemented by driver/.test(err.message)) {
    err.message += ` — create the connection via mongoose.createConnection() instead of ${conn.constructor.name}`;
  }
  throw err;
}

Prevention

When it happens

Trigger: conn.setClient(client) where conn is a base Connection instance or a custom subclass without the override, instead of one produced by mongoose.createConnection().

Common situations: Custom driver adapters; constructing Connection directly; test doubles standing in for real connections.

Related errors

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