Mongoose 9 Migration Guide: What Actually Breaks in a Real MERN App

If you run npm update on a Mongoose 8 project today, you might end up on Mongoose 9 without meaning to, depending on how your package.json is pinned. That's when the fun starts.

Mongoose 9 shipped in November 2025 as what the maintainers call the "async maturity release." The pitch is good: cleaner stack traces, no more mystery processTicksAndRejections lines, stricter TypeScript. The reality for anyone running a real app is that it quietly breaks a handful of patterns most MERN codebases still use, especially anything written before 2023.

I upgraded three projects to Mongoose 9 over the past few weeks. Here's what actually broke, in the order I hit it.

This is the one. If your schema has anything that looks like this, it's gone in Mongoose 9:

The next callback parameter is no longer supported on pre() hooks. Calling next() just does nothing now, silently, no error, no console warning. Your hook still fires, but nothing after it runs the way you expect, and any async work you were doing before calling next() may not finish before the save resolves.

The fix is mechanical but you have to touch every hook:

The same applies to done() in other hook types. If it used to take a callback, it doesn't anymore.

This is the part the official migration guide doesn't spell out clearly enough. A lot of MERN auth setups lean on passport-local-mongoose or mongoose-unique-validator, both of which attach their own pre('save') hooks internally.

mongoose-unique-validator specifically relies on pre-save validation to convert MongoDB's raw E11000 duplicate key error into a normal Mongoose ValidationError. If you're running an old version of the plugin, its internal hook may still use the old callback signature, which means it stops doing its job after the Mongoose 9 upgrade, and your app starts throwing raw MongoDB errors again instead of clean validation errors your frontend expects.

This one bit me in a route handler:

In Mongoose 8 this quietly created something, wrong, but something. In Mongoose 9 it throws. mongoose.isValidObjectId() changed too, for a handful of edge-case inputs the return value flipped from what it used to be.

If any older code constructs ObjectIds from loosely-typed input, like an ID pulled straight from a query string without validation, run your test suite before assuming this doesn't touch you.

If your project uses Mongoose's generated types, expect new red squiggles after the upgrade. Query filters are now checked more strictly against your schema shape:

This is a genuine improvement, it catches real bugs, but a clean tsc run pre-upgrade won't stay clean post-upgrade. Budget time for this specifically if your codebase does any loosely-typed query building. If you're also mid-upgrade on the compiler itself, see our TypeScript 7 migration guide for what changes there.

None of this is exotic. It's the kind of upgrade where nothing crashes on npm install, everything looks fine, and then a week later someone notices duplicate accounts started getting created because the unique validator plugin silently stopped catching E11000 errors. Work through these six steps in order and you'll catch it before it ships.

A green test suite after the upgrade tells you less than it feels like it does. Most existing tests check that a save resolves without throwing, not that a hook actually ran and produced the side effect it's supposed to. A hook that got silently skipped because of the callback change will still let those tests pass.

Write at least one explicit assertion per hook that checks the side effect itself, not just the absence of an error. For the updatedAt example from earlier, that means fetching the document after the save and checking the field actually changed, not just that save() didn't reject.

Beyond unit tests, run the upgraded app against a staging environment with production-shaped data before touching the real deployment. Watch application logs specifically for raw E11000 duplicate key errors reaching the response layer, that's the exact symptom of a validator plugin whose internal hook stopped firing.

Give it more than a single deploy cycle before calling it safe. Duplicate account creation from a broken unique validator often doesn't show up until real signup traffic hits the endpoint, which can be days after the code shipped.

If something breaks after the upgrade ships, the fastest fix is usually a straight revert: commit the previous package.json and package-lock.json together, then redeploy with npm ci so the exact locked versions install instead of whatever satisfies the range.

You don't need to revert the hook syntax you converted in step 2 along with the version number. Mongoose has supported promise-returning, async hooks alongside the callback style for a long time, well before version 9, so the async hooks you wrote for the upgrade keep working if you roll back to 8.x. That means a rollback is one change, not two.

After rolling back, keep watching for the same symptom that told you something was wrong in the first place: duplicate accounts or raw MongoDB errors reaching users. If those stop appearing, the rollback fixed it. If they don't, the bug wasn't the Mongoose upgrade to begin with.

If you're actively maintaining the app and want the async stack traces, genuinely useful for debugging, yes. If the app is in maintenance mode and stable, there's no urgency. Mongoose 8.x keeps getting fixes through at least February 2026. Either way, pin your version deliberately instead of letting a ^8.0.0 range quietly pull in 9.x on your next npm install.

Data-modeling questions come up constantly during a migration like this, especially around aggregation pipelines that touch fields your schema validation now checks more strictly. If you're debugging one, our PipelineExplain tool walks through an aggregation pipeline stage by stage. And if you want to brush up on the underlying concepts before diving into schema changes, see our NoSQL interview questions guide.