{"record":{"id":"1310e466f943a654","repo":"Automattic/mongoose","slug":"connection-createclient-not-implemented-by-driver","errorCode":null,"errorMessage":"Connection#createClient not implemented by driver","messagePattern":"Connection#createClient not implemented by driver","errorType":"exception","errorClass":"MongooseError","httpStatus":null,"severity":"error","filePath":"lib/connection.js","lineNumber":1744,"sourceCode":" *\n *     conn.getClient(); // MongoClient { ... }\n *     conn.readyState; // 1, means 'CONNECTED'\n *\n * @api public\n * @param {MongClient} client The Client to set to be used.\n * @return {Connection} this\n */\n\nConnection.prototype.setClient = function setClient() {\n  throw new MongooseError('Connection#setClient not implemented by driver');\n};\n\n/*!\n * Called internally by `openUri()` to create a MongoClient instance.\n */\n\nConnection.prototype.createClient = function createClient() {\n  throw new MongooseError('Connection#createClient not implemented by driver');\n};\n\n/**\n * Syncs all the indexes for the models registered with this connection.\n *\n * @param {object} [options]\n * @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.\n * @return {Promise<object>} Returns a Promise, when the Promise resolves the value is a list of the dropped indexes.\n */\nConnection.prototype.syncIndexes = async function syncIndexes(options = {}) {\n  const result = {};\n  const errorsMap = { };\n\n  const { continueOnError } = options;\n  delete options.continueOnError;\n\n  for (const model of Object.values(this.models)) {\n    try {","sourceCodeStart":1726,"sourceCodeEnd":1762,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/connection.js#L1726-L1762","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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')","Otherwise implement createClient() in your Connection subclass so it constructs the underlying client and returns this","If you never meant to supply a custom driver, remove the driver/ConnectionClass customization and let Mongoose use the default mongodb driver"],"exampleFix":"// before\nclass MyConnection extends mongoose.Connection {\n  // implements connect(), but not createClient()\n}\nmongoose.createConnection(uri, { ConnectionClass: MyConnection }); // throws: createClient not implemented\n\n// after\nconst NativeConnection = require('mongoose/lib/drivers/node-mongodb-native/connection');\nclass MyConnection extends NativeConnection {\n  // createClient() inherited; override only what you need\n}\nmongoose.createConnection(uri, { ConnectionClass: MyConnection });","handlingStrategy":"validation","validationCode":"const baseCreateClient = mongoose.Connection.prototype.createClient;\n// before connecting: verify the custom driver actually implements createClient()\nif (MyConnection.prototype.createClient === baseCreateClient) {\n  throw new Error('MyConnection does not implement createClient(); extend the native driver Connection');\n}","typeGuard":"const implementsCreateClient = (Ctor) =>\n  typeof Ctor === 'function' &&\n  typeof Ctor.prototype.createClient === 'function' &&\n  Ctor.prototype.createClient !== mongoose.Connection.prototype.createClient;","tryCatchPattern":"try {\n  await conn.asPromise();\n} catch (err) {\n  if (/createClient not implemented/.test(err.message)) {\n    // custom driver is incomplete — fix the Connection class, do not retry\n    throw new Error('Custom driver missing createClient(): ' + err.message);\n  }\n  throw err;\n}","preventionTips":["Prefer extending mongoose/lib/drivers/node-mongodb-native/connection over the abstract base when customizing connections","Pin the Mongoose major version and re-test custom drivers on every upgrade — the internal driver interface is not semver-stable","Fail fast at startup: assert createClient is overridden before the first connect()"],"tags":["connection","custom-driver","openuri","mongoose"],"backgroundTag":"abstract-method-not-implemented","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}