mongoose

library0.0.1jsnpmunverified

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.

database serialization web-framework

npm install mongoose

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGOOSE

mongoose

databasejavascriptv0.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mongoose

✓ import mongoose from 'mongoose';

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.

import mongoose, { Schema, model } from 'mongoose'; async function main() { // Replace with your MongoDB connection string const uri = process.env.MONGO_URI ?? 'mongodb://127.0.0.1:27017/test'; try { await mongoose.connect(uri); console.log('Connected to MongoDB!'); interface IUser { name: string; email: string; } const UserSchema = new Schema<IUser>({ name: { type: String, required: true }, email: { type: String, required: true, unique: true } }); const UserModel = model<IUser>('User', UserSchema); // Create a new user const newUser = new UserModel({ name: 'Alice Wonderland', email: 'alice@example.com' }); await newUser.save(); console.log('User saved:', newUser); // Find a user const foundUser = await UserModel.findOne({ email: 'alice@example.com' }); console.log('User found:', foundUser); } catch (error) { console.error('MongoDB connection or operation error:', error); process.exit(1); } finally { await mongoose.disconnect(); console.log('Disconnected from MongoDB.'); } } main();

Debug

Known issues

breakingMongoose 9.x requires Node.js version 20.19.0 or higher.

fix

Upgrade your Node.js environment to version 20.19.0 or newer.

affects: >=9.0.0

breakingMongoose 9.0 introduced significant backwards-incompatible changes.

fix

Refer to the official migration guide for Mongoose 9.0 at `https://mongoosejs.com/docs/migrating_to_9.html`.

affects: >=9.0.0

deprecatedThe `document.getChanges()` method is deprecated in favor of `document.$getChanges()`.

fix

Replace calls to `document.getChanges()` with `document.$getChanges()`.

affects: >=9.4.0

gotchaAs of Mongoose 9.3.2, passing `null` or `undefined` as options to certain Mongoose methods will now throw an error.

fix

Ensure all options passed to Mongoose methods are valid objects or primitive values, not `null` or `undefined`.

affects: >=9.3.2

gotchaA 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.

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.

affects: 9.4.1

Errors

Common errors & fixes

MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017

Mongoose could not connect to the MongoDB server, likely because it is not running or is listening on a different address/port.

fix

Ensure your MongoDB instance is running and accessible at the specified connection URI (e.g., `mongodb://127.0.0.1:27017/`).

ValidationError: User validation failed: name: Path `name` is required.

You attempted to save a document that is missing a required field, or a field failed schema validation rules.

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.

CastError: Cast to ObjectId failed for value "invalid-id" at path "_id"

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`.

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.

MongooseError: Options cannot be null or undefined. Received: null

You passed `null` or `undefined` as an options object to a Mongoose method (e.g., `Model.find(query, null)`).

fix

Provide a valid options object (even an empty one `{}`) or omit the options parameter entirely if no options are needed.

Cannot find module 'mongoose'

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.

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`).

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/Automattic/mongoose ↗

packagehttps://www.npmjs.com/package/mongoose ↗

homepagehttps://mongoosejs.com ↗