{"id":14714,"library":"mongoose","title":"Mongoose","description":"Mongoose is a popular MongoDB object modeling tool (ODM) for Node.js and Deno, designed for asynchronous environments. It provides a schema-based solution to model application data, offering powerful validation, querying, and middleware capabilities. The current stable version is 9.4.1, with frequent patch and minor releases addressing bug fixes and new features.","status":"active","version":"9.4.1","language":"javascript","source_language":"en","source_url":"git://github.com/Automattic/mongoose","tags":["javascript","mongodb","document","model","schema","database","odm","data","datastore","typescript"],"install":[{"cmd":"npm install mongoose","lang":"bash","label":"npm"},{"cmd":"yarn add mongoose","lang":"bash","label":"yarn"},{"cmd":"pnpm add mongoose","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"symbol":"mongoose","correct":"import mongoose from 'mongoose';"}],"quickstart":{"code":"import mongoose, { Schema, model } from 'mongoose';\n\nasync function main() {\n  // Replace with your MongoDB connection string\n  const uri = process.env.MONGO_URI ?? 'mongodb://127.0.0.1:27017/test';\n\n  try {\n    await mongoose.connect(uri);\n    console.log('Connected to MongoDB!');\n\n    interface IUser {\n      name: string;\n      email: string;\n    }\n\n    const UserSchema = new Schema<IUser>({\n      name: { type: String, required: true },\n      email: { type: String, required: true, unique: true }\n    });\n\n    const UserModel = model<IUser>('User', UserSchema);\n\n    // Create a new user\n    const newUser = new UserModel({\n      name: 'Alice Wonderland',\n      email: 'alice@example.com'\n    });\n\n    await newUser.save();\n    console.log('User saved:', newUser);\n\n    // Find a user\n    const foundUser = await UserModel.findOne({ email: 'alice@example.com' });\n    console.log('User found:', foundUser);\n\n  } catch (error) {\n    console.error('MongoDB connection or operation error:', error);\n    process.exit(1);\n  } finally {\n    await mongoose.disconnect();\n    console.log('Disconnected from MongoDB.');\n  }\n}\n\nmain();","lang":"typescript","description":"This quickstart demonstrates how to connect to a MongoDB database, define a simple Mongoose schema and model, create a new document, save it, and then query for it."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20.19.0 or newer.","message":"Mongoose 9.x requires Node.js version 20.19.0 or higher.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Refer to the official migration guide for Mongoose 9.0 at `https://mongoosejs.com/docs/migrating_to_9.html`.","message":"Mongoose 9.0 introduced significant backwards-incompatible changes.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Replace calls to `document.getChanges()` with `document.$getChanges()`.","message":"The `document.getChanges()` method is deprecated in favor of `document.$getChanges()`.","severity":"deprecated","affected_versions":">=9.4.0"},{"fix":"Ensure all options passed to Mongoose methods are valid objects or primitive values, not `null` or `undefined`.","message":"As of Mongoose 9.3.2, passing `null` or `undefined` as options to certain Mongoose methods will now throw an error.","severity":"gotcha","affected_versions":">=9.3.2"},{"fix":"Review your `setDefaultsOnInsert` logic for upserts and adjust if you expected setters to run on default values, as this behavior is now off by default again.","message":"A fix for running setters on default values during upsert operations was reverted in 9.4.1. If you relied on this short-lived behavior, it will no longer apply.","severity":"gotcha","affected_versions":"9.4.1"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"fix":"Ensure your MongoDB instance is running and accessible at the specified connection URI (e.g., `mongodb://127.0.0.1:27017/`).","cause":"Mongoose could not connect to the MongoDB server, likely because it is not running or is listening on a different address/port.","error":"MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017"},{"fix":"Provide values for all required fields as defined in your Mongoose Schema before saving the document. Check other validation rules like `minlength`, `maxlength`, `enum`, etc.","cause":"You attempted to save a document that is missing a required field, or a field failed schema validation rules.","error":"ValidationError: User validation failed: name: Path `name` is required."},{"fix":"Ensure that the value you are providing for `_id` or any other `ObjectId` field is a valid 24-character hexadecimal string or an actual `ObjectId` instance.","cause":"Mongoose attempted to cast an invalid value (e.g., a non-string or malformed string) into an `ObjectId` type, typically during a query for a document by its `_id`.","error":"CastError: Cast to ObjectId failed for value \"invalid-id\" at path \"_id\""},{"fix":"Provide a valid options object (even an empty one `{}`) or omit the options parameter entirely if no options are needed.","cause":"You passed `null` or `undefined` as an options object to a Mongoose method (e.g., `Model.find(query, null)`).","error":"MongooseError: Options cannot be null or undefined. Received: null"},{"fix":"Install the package using `npm install mongoose`, `yarn add mongoose`, or `pnpm add mongoose`. If using ESM, ensure your `package.json` is configured correctly (e.g., `type: module`).","cause":"The `mongoose` package is not installed in your project's `node_modules` directory, or there's an issue with module resolution in an ESM context.","error":"Cannot find module 'mongoose'"}],"ecosystem":"npm"}