{"record":{"id":"a37d4eb4d8dbe513","repo":"Automattic/mongoose","slug":"the-connection-passed-to-useconnection-has-a-d","errorCode":null,"errorMessage":"The connection passed to `useConnection()` has a different version of Mongoose (${connection.base?.version}) than the model you are using (${this.db?.base?.version}).","messagePattern":"The connection passed to `useConnection\\(\\)` has a different version of Mongoose \\((.+?)\\) than the model you are using \\((.+?)\\)\\.","errorType":"exception","errorClass":"MongooseError","httpStatus":null,"severity":"error","filePath":"lib/model.js","lineNumber":202,"sourceCode":" *\n *     conn2.model('User') === UserModel; // true\n *     mongoose.model('User'); // Throws 'MissingSchemaError'\n *\n * Note: `useConnection()` does **not** apply any [connection-level plugins](https://mongoosejs.com/docs/api/connection.html#Connection.prototype.plugin()) from the new connection.\n * If you use `useConnection()` to switch a model's connection, the model will still have the old connection's plugins.\n *\n * @function useConnection\n * @param {Connection} connection The new connection to use\n * @return {Model} this\n * @api public\n */\n\nModel.useConnection = function useConnection(connection) {\n  if (typeof connection?.model !== 'function' || typeof connection.collection !== 'function' || typeof connection.base?.version !== 'string') {\n    throw new MongooseError('`useConnection()` requires a Mongoose connection.');\n  }\n  if (this.db?.base?.version && this.db?.base?.version !== connection.base?.version) {\n    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}).`);\n  }\n  if (this.db) {\n    delete this.db.models[this.modelName];\n    delete this.prototype.db;\n    delete this.prototype[modelDbSymbol];\n    delete this.prototype.collection;\n    delete this.prototype.$collection;\n    delete this.prototype[modelCollectionSymbol];\n  }\n\n  this.db = connection;\n  const collection = connection.collection(this.collection.collectionName, connection.options);\n  this.prototype.collection = collection;\n  this.prototype.$collection = collection;\n  this.prototype[modelCollectionSymbol] = collection;\n  this.prototype.db = connection;\n  this.prototype[modelDbSymbol] = connection;\n  this.collection = collection;","sourceCodeStart":184,"sourceCodeEnd":220,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/model.js#L184-L220","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)"],"exampleFix":"// before (two copies: app uses mongoose@8, dep resolved mongoose@6)\nconst conn = require('some-plugin').connection;\nUserModel.useConnection(conn); // version mismatch\n\n// after (package.json)\n\"resolutions\": { \"mongoose\": \"^8.0.0\" }\n// then: npm dedupe && npm ls mongoose  # single version","handlingStrategy":"validation","validationCode":"// Fail fast when model and connection come from different mongoose copies\nfunction assertSameMongoose(model, conn) {\n  const mv = model.db?.base?.version;\n  const cv = conn?.base?.version;\n  if (mv && cv && mv !== cv) {\n    throw new Error(`Mongoose version mismatch: model ${mv} vs connection ${cv} — dedupe node_modules/mongoose`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  model.useConnection(conn);\n} catch (err) {\n  if (err instanceof mongoose.MongooseError && /different version of Mongoose/.test(err.message)) {\n    // recompile the model on the new connection: conn.model(model.modelName, schema)\n  } else throw err;\n}","preventionTips":["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"],"tags":["mongoose","connection","version-conflict","duplicate-dependency","monorepo"],"backgroundTag":"duplicate-package-version","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}