mongoose
| Property | Value |
|---|---|
| Package | mongoose |
| Versions Covered | >=5.0.0 |
| Contract Version | 1.0.0 |
| Status | production |
| Last Verified | 2026-02-25 |
| Maintainer | corpus-team |
Installation
npm install mongoose
Covered Functions
This contract covers 16 function(s):
find()
Queries the database and returns an array of documents matching the filter
Import:
import { find } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - connection-error-no-try-catch
Condition: Database connection failed or was interrupted
Throws: MongooseError or MongoError
Required Handling:
Caller MUST wrap in try-catch or use .catch(). Handle connection errors separately from query results. Implement retry logic for transient connection issues.
📖 Source
🔴 ERROR - cast-error-no-try-catch
Condition: Query parameter cannot be cast to expected type
Throws: CastError
Required Handling:
Caller MUST wrap in try-catch or use .catch(). Validate query parameters before passing to mongoose. Handle CastError separately from other errors.
📖 Source
findOne()
Queries the database and returns a single document matching the filter
Import:
import { findOne } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - connection-error-no-try-catch
Condition: Database connection failed
Throws: MongooseError or MongoError
Required Handling:
Caller MUST wrap in try-catch or use .catch() to handle connection errors
📖 Source
🔴 ERROR - cast-error-no-try-catch
Condition: Query parameter casting failed
Throws: CastError
Required Handling:
Caller MUST wrap in try-catch to handle type casting errors
📖 Source
findById()
Finds a single document by its _id field
Import:
import { findById } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - cast-error-no-try-catch-invalid-id
Condition: Provided ID is not a valid ObjectId format
Throws: CastError with kind: 'ObjectId'
Required Handling:
Caller MUST wrap in try-catch or use .catch(). Common when user input is passed directly as ID. Validate ID format before querying.
📖 Source
🔴 ERROR - connection-error-no-try-catch
Condition: Database connection failed
Throws: MongooseError
Required Handling:
Caller MUST handle connection errors
📖 Source
create()
Creates one or more documents in the database
Import:
import { create } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - validation-error-no-try-catch
Condition: Document validation failed (missing required fields, wrong types, custom validators)
Throws: ValidationError with errors object containing field-specific ValidatorErrors
Required Handling:
Caller MUST wrap in try-catch or use .catch(). Check error.name === 'ValidationError' and inspect error.errors object. Each field error is accessible via error.errors[fieldName].
📖 Source
🔴 ERROR - duplicate-key-error-no-try-catch
Condition: Unique constraint violation (E11000 error)
Throws: MongoError with code: 11000
Required Handling:
Caller MUST wrap in try-catch and check error.code === 11000. This is NOT a ValidationError - it comes from MongoDB driver. Extract duplicate field from error message or error.keyPattern.
📖 Source
🔴 ERROR - connection-error-no-try-catch
Condition: Database connection failed
Throws: MongooseError
Required Handling:
Caller MUST handle connection errors with retry logic
📖 Source
insertMany()
Inserts multiple documents into the database in a single operation
Import:
import { insertMany } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - validation-error-no-try-catch
Condition: One or more documents fail validation
Throws: ValidationError
Required Handling:
Caller MUST wrap in try-catch. Default behavior stops on first error; use ordered:false to continue on errors.
📖 Source
🔴 ERROR - duplicate-key-error-no-try-catch
Condition: Duplicate key constraint violation
Throws: MongoError with code: 11000
Required Handling:
Caller MUST wrap in try-catch and handle duplicate key errors
📖 Source
updateOne()
Updates a single document matching the filter
Import:
import { updateOne } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - validation-error-no-try-catch
Condition: Update violates validation rules
Throws: ValidationError
Required Handling:
Caller MUST wrap in try-catch to handle validation errors
📖 Source
🔴 ERROR - cast-error-no-try-catch
Condition: Update value cannot be cast to schema type
Throws: CastError
Required Handling:
Caller MUST wrap in try-catch to handle type errors
📖 Source
🔴 ERROR - connection-error-no-try-catch
Condition: Database connection failed
Throws: MongooseError
Required Handling:
Caller MUST handle connection errors
📖 Source
findByIdAndUpdate()
Finds a document by ID and updates it, returning the document
Import:
import { findByIdAndUpdate } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - prototype-pollution-cve-2023-3696-no-try-catch
Condition: Malicious update payload exploits prototype pollution vulnerability
Throws: May not throw - vulnerability allows arbitrary code execution
Required Handling:
Caller MUST wrap in try-catch. CRITICAL: Ensure mongoose version = 5.13.20, 6.4.6, or 7.3.1 to patch CVE-2023-3696. Validate and sanitize all update payloads from user input.
📖 Source
🔴 ERROR - validation-error-no-try-catch
Condition: Update violates validation rules
Throws: ValidationError
Required Handling:
Caller MUST wrap in try-catch
📖 Source
🔴 ERROR - cast-error-no-try-catch
Condition: Invalid ObjectId or type casting failure
Throws: CastError
Required Handling:
Caller MUST wrap in try-catch
📖 Source
findOneAndUpdate()
Finds a document matching filter and updates it
Import:
import { findOneAndUpdate } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - prototype-pollution-cve-2023-3696-no-try-catch
Condition: Vulnerable to prototype pollution attacks
Throws: May not throw - allows RCE
Required Handling:
Caller MUST wrap in try-catch and validate input. Upgrade mongoose to patched version.
📖 Source
🔴 ERROR - validation-error-no-try-catch
Condition: Update violates validation
Throws: ValidationError
Required Handling:
Caller MUST wrap in try-catch
📖 Source
deleteOne()
Deletes a single document matching the filter
Import:
import { deleteOne } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - connection-error-no-try-catch
Condition: Database connection failed
Throws: MongooseError
Required Handling:
Caller MUST wrap in try-catch
📖 Source
findByIdAndDelete()
Finds a document by ID and deletes it
Import:
import { findByIdAndDelete } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - cast-error-no-try-catch
Condition: Invalid ObjectId format
Throws: CastError
Required Handling:
Caller MUST wrap in try-catch
📖 Source
🔴 ERROR - connection-error-no-try-catch
Condition: Database connection failed
Throws: MongooseError
Required Handling:
Caller MUST wrap in try-catch
📖 Source
save()
Saves document changes to the database
Import:
import { save } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - validation-error-no-try-catch
Condition: Document validation failed
Throws: ValidationError with errors object
Required Handling:
Caller MUST wrap in try-catch. Most common error when saving documents. Inspect error.errors for field-specific validation failures.
📖 Source
🔴 ERROR - duplicate-key-error-no-try-catch
Condition: Unique constraint violation
Throws: MongoError with code: 11000
Required Handling:
Caller MUST wrap in try-catch and check error.code === 11000. Common when saving new documents with existing unique field values.
📖 Source
🔴 ERROR - connection-error-no-try-catch
Condition: Database connection failed
Throws: MongooseError
Required Handling:
Caller MUST wrap in try-catch
📖 Source
exec()
Executes the query and returns a promise
Import:
import { exec } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - query-error-no-try-catch
Condition: Query execution failed
Throws: MongooseError, CastError, or ValidationError depending on failure type
Required Handling:
Caller MUST wrap in try-catch or use .catch(). .exec() is the terminal operation for query chains. All query errors surface here.
📖 Source
orFail()
Executes query and throws DocumentNotFoundError if no results
Import:
import { orFail } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - document-not-found-no-try-catch
Condition: No documents match the query
Throws: DocumentNotFoundError
Required Handling:
Caller MUST wrap in try-catch. .orFail() is explicitly designed to throw when no results found. Use this when document existence is mandatory.
📖 Source
connect()
Establishes connection to MongoDB database
Import:
import { connect } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - connection-failed-no-try-catch
Condition: Cannot connect to MongoDB (network, auth, or invalid connection string)
Throws: MongooseError or MongoError
Required Handling:
Caller MUST wrap in try-catch. Connection failures should stop application startup. Log error details and exit gracefully.
📖 Source
aggregate()
Executes an aggregation pipeline on the collection
Import:
import { aggregate } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - aggregation-error-no-try-catch
Condition: Invalid pipeline stage or aggregation failure
Throws: MongooseError or MongoError
Required Handling:
Caller MUST wrap in try-catch. Aggregation pipelines can fail with complex stage errors.
📖 Source
countDocuments()
Counts documents matching the filter
Import:
import { countDocuments } from 'mongoose';
Postconditions
What happens after calling this function:
🔴 ERROR - connection-error-no-try-catch
Condition: Database connection failed
Throws: MongooseError
Required Handling:
Caller MUST wrap in try-catch
📖 Source
Example: Proper Error Handling
import mongoose from 'mongoose';
async function example() {
try {
const result = await find(/* args */);
// Handle success
return result;
} catch (error) {
// Handle error according to contract postconditions
console.error('Error:', error);
throw error;
}
}