Automattic/mongoose · error · MongooseError

Connection#createClient not implemented by driver

Error message

Connection#createClient not implemented by driver

What it means

Mongoose's base Connection class defines createClient() as an abstract stub; the bundled MongoDB driver subclass (lib/drivers/node-mongodb-native/connection.js) overrides it to actually build a MongoClient. This error means the connection object servicing openUri()/mongoose.connect() never got a driver-specific createClient() implementation, so Mongoose cannot construct a client. It is effectively an abstract-method error: the driver contract was not fulfilled.

Source

Thrown at lib/connection.js:1744

 *
 *     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 = {}) {
  const result = {};
  const errorsMap = { };

  const { continueOnError } = options;
  delete options.continueOnError;

  for (const model of Object.values(this.models)) {
    try {

View on GitHub (pinned to 49cdab0136)

Solutions

1. Make your custom connection extend the bundled native driver's Connection so it inherits createClient(): const NativeConnection = require('mongoose/lib/drivers/node-mongodb-native/connection')
2. Otherwise implement createClient() in your Connection subclass so it constructs the underlying client and returns this
3. If you never meant to supply a custom driver, remove the driver/ConnectionClass customization and let Mongoose use the default mongodb driver

Example fix

// before
class MyConnection extends mongoose.Connection {
  // implements connect(), but not createClient()
}
mongoose.createConnection(uri, { ConnectionClass: MyConnection }); // throws: createClient not implemented

// after
const NativeConnection = require('mongoose/lib/drivers/node-mongodb-native/connection');
class MyConnection extends NativeConnection {
  // createClient() inherited; override only what you need
}
mongoose.createConnection(uri, { ConnectionClass: MyConnection });

const baseCreateClient = mongoose.Connection.prototype.createClient;
// before connecting: verify the custom driver actually implements createClient()
if (MyConnection.prototype.createClient === baseCreateClient) {
  throw new Error('MyConnection does not implement createClient(); extend the native driver Connection');
}

const implementsCreateClient = (Ctor) =>
  typeof Ctor === 'function' &&
  typeof Ctor.prototype.createClient === 'function' &&
  Ctor.prototype.createClient !== mongoose.Connection.prototype.createClient;

try {
  await conn.asPromise();
} catch (err) {
  if (/createClient not implemented/.test(err.message)) {
    // custom driver is incomplete — fix the Connection class, do not retry
    throw new Error('Custom driver missing createClient(): ' + err.message);
  }
  throw err;
}

When it happens

Trigger: Registering a custom driver or Connection class (mongoose.setDriver(), a `driver` option, or subclassing mongoose.Connection) that does not implement createClient(), then calling mongoose.connect(uri) or connection.openUri(uri); also directly instantiating the base Connection class and opening it.

Common situations: Writing a custom Mongoose driver (for a MongoDB-compatible proxy or a test double); upgrading Mongoose across a major version where the internal driver interface changed from connect()-style to createClient(); copying old driver plugins that implement the pre-6.x interface.

Related errors

• Cannot call `${this.name}.${i}()` before initial connection
• No connections to database "${name}" found
• Connection has been closed and destroyed, and cannot be used
• `useConnection()` requires a Mongoose connection.
• The connection passed to `useConnection()` has a different v

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