Fixing Mongoose 'TypeError: doc.save is not a function' When Using .lean()

The Problem: Performance vs. FunctionalityIt’s a common performance optimization: you chain .lean() to your Mongoose query to shave off execution time and reduce memory overhead. By default, Mongoose documents are heavy. They carry internal state, validation logic, and change-tracking hooks that can make them up to 10x larger in memory than a standard JSON object.

The trouble starts when you try to treat that lightweight object like a full Mongoose document. You modify a property and call doc.save(), only to watch your application crash:

TypeError: doc.save is not a function

This happens because .lean() tells Mongoose to skip the process of creating a full Mongoose Document instance. Instead, it returns a Plain Old JavaScript Object (POJO). These objects are fast, but they lack the internal Mongoose "magic," including .save(), .populate(), and .validate().

The Debugging ProcessTo confirm that .lean() is causing your headache, inspect the document's constructor before calling the save method. A standard Mongoose document includes internal properties like $__ and isNew, which won't exist on a lean object.

const user = await User.findOne({ email: 'dev@example.com' }).lean();

console.log(user instanceof mongoose.Document); // Returns: false
console.log(user.constructor.name); // Returns: Object (instead of 'model')

user.name = 'Updated Name';
await user.save(); // This triggers the TypeError

If the output shows a plain Object, the prototype chain is gone. You cannot use any Mongoose-specific methods on it.

Solution 1: The Direct Fix (Remove .lean())The most straightforward solution is to remove .lean() if you plan to modify the document and save it. When you omit .lean(), Mongoose returns a full document with all its methods intact.

// BEFORE
const user = await User.findById(id).lean();

// AFTER (Fixed)
const user = await User.findById(id);
user.status = 'active';
await user.save();

Choose this approach when you need to trigger Mongoose middleware, such as pre('save') hooks, or when you rely on complex schema validation.

Solution 2: Use Atomic Update MethodsSometimes you want the speed of .lean() for the initial fetch, or perhaps you only need to flip a single flag in the database. In these cases, use findOneAndUpdate or updateOne. These methods bypass the document instance entirely and talk directly to MongoDB.

const userId = '60d5ec...';

// 1. Fetch with lean for fast read-only logic
const user = await User.findById(userId).lean();

// 2. Update directly via the model
await User.updateOne({ _id: userId }, { $set: { status: 'active' } });

This is often the most efficient route. It avoids the CPU overhead of the Mongoose document lifecycle—validation, hooks, and change tracking—making it ideal for high-traffic write operations.

Solution 3: Rehydrating the Object (Advanced)You might occasionally find yourself with a plain object from a cache (like Redis) that you suddenly need to turn back into a Mongoose document. For these edge cases, use model.hydrate().

const leanDoc = await User.findOne({ name: 'Alice' }).lean();

// Convert the POJO back into a full Mongoose Document
const doc = User.hydrate(leanDoc);

doc.status = 'inactive';
await doc.save(); // This now works!

Keep in mind that hydrate() creates a document that Mongoose assumes already exists in the database. It won't trigger isNew logic unless you manually toggle the state.

Verification: Confirming the UpdateOnce you apply a fix, ensure the data actually reached your MongoDB collection. You can verify this using a few different methods:

• Check the returned object from await doc.save(); it should contain the updated fields.- Use a GUI like MongoDB Compass or the Mongo shell to run: db.users.find({ _id: ... }).- Log a success message immediately after the call to ensure the event loop didn't hang.## Key Takeaways- Lean is for Reads: Reserve .lean() for GET APIs, dashboard exports, or read-heavy templates where performance is the priority.- Prototypes Matter: Methods like .save() live on the Document class prototype. Plain objects don't inherit them.- Pick the Right Tool: If you are only updating one field, updateOne is faster and uses less memory than the find -> modify -> save pattern.