Automattic/mongoose · error · MongooseError

The connection passed to `useConnection()` has a different v

Error message

The connection passed to `useConnection()` has a different version of Mongoose (${connection.base?.version}) than the model you are using (${this.db?.base?.version}).

What it means

useConnection() refuses to attach a model to a connection created by a different copy of Mongoose: it compares the model's base.version with the connection's base.version and throws when they differ. Two separate mongoose instances cannot share models safely (internal symbols and prototypes differ), so Mongoose fails fast. This almost always indicates duplicate mongoose packages in node_modules.

Source

Thrown at lib/model.js:202

 *
 *     conn2.model('User') === UserModel; // true
 *     mongoose.model('User'); // Throws 'MissingSchemaError'
 *
 * Note: `useConnection()` does **not** apply any [connection-level plugins](https://mongoosejs.com/docs/api/connection.html#Connection.prototype.plugin()) from the new connection.
 * If you use `useConnection()` to switch a model's connection, the model will still have the old connection's plugins.
 *
 * @function useConnection
 * @param {Connection} connection The new connection to use
 * @return {Model} this
 * @api public
 */

Model.useConnection = function useConnection(connection) {
  if (typeof connection?.model !== 'function' || typeof connection.collection !== 'function' || typeof connection.base?.version !== 'string') {
    throw new MongooseError('`useConnection()` requires a Mongoose connection.');
  }
  if (this.db?.base?.version && this.db?.base?.version !== connection.base?.version) {
    throw new MongooseError(`The connection passed to \`useConnection()\` has a different version of Mongoose (${connection.base?.version}) than the model you are using (${this.db?.base?.version}).`);
  }
  if (this.db) {
    delete this.db.models[this.modelName];
    delete this.prototype.db;
    delete this.prototype[modelDbSymbol];
    delete this.prototype.collection;
    delete this.prototype.$collection;
    delete this.prototype[modelCollectionSymbol];
  }

  this.db = connection;
  const collection = connection.collection(this.collection.collectionName, connection.options);
  this.prototype.collection = collection;
  this.prototype.$collection = collection;
  this.prototype[modelCollectionSymbol] = collection;
  this.prototype.db = connection;
  this.prototype[modelDbSymbol] = connection;
  this.collection = collection;

View on GitHub (pinned to 49cdab0136)

Solutions

Deduplicate mongoose: run npm ls mongoose, then use npm dedupe, yarn resolutions, or pnpm overrides so every importer shares one copy
Import the model and the connection from the same mongoose instance — pass the app's connection object, not one created inside a dependency
If two versions are unavoidable, recompile the model on the new connection instead: conn.model('User', userSchema)

Example fix

// before (two copies: app uses mongoose@8, dep resolved mongoose@6)
const conn = require('some-plugin').connection;
UserModel.useConnection(conn); // version mismatch

// after (package.json)
"resolutions": { "mongoose": "^8.0.0" }
// then: npm dedupe && npm ls mongoose  # single version

Defensive patterns

Strategy: validation

Validate before calling

// Fail fast when model and connection come from different mongoose copies
function assertSameMongoose(model, conn) {
  const mv = model.db?.base?.version;
  const cv = conn?.base?.version;
  if (mv && cv && mv !== cv) {
    throw new Error(`Mongoose version mismatch: model ${mv} vs connection ${cv} — dedupe node_modules/mongoose`);
  }
}

Try / catch

try {
  model.useConnection(conn);
} catch (err) {
  if (err instanceof mongoose.MongooseError && /different version of Mongoose/.test(err.message)) {
    // recompile the model on the new connection: conn.model(model.modelName, schema)
  } else throw err;
}

Prevention

Run npm ls mongoose in CI and fail on more than one resolved version
Use resolutions/overrides to pin one mongoose across monorepos and plugins
Create models and connections from the same import of mongoose in each process

When it happens

Trigger: model.useConnection(conn) where conn comes from another mongoose instance — e.g. a plugin or workspace package that resolved its own mongoose@6 while the app uses mongoose@7, or different import specifiers/bundler aliases resolving to two copies.

Common situations: Monorepos where a dependency pins an older mongoose; plugins pulling their own copy; pnpm/yarn/PnP strict resolution; mixed ESM/CJS imports creating two instances; npm hoisting quirks.

Related errors

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