The 2 AM On-Call NightmareYou’re monitoring the logs when a sudden spike of VersionError alerts appears. Your order processing pipeline, which handled low traffic perfectly during staging, is now failing under the weight of real users. The logs show a recurring culprit:
VersionError: No matching document found for id "65f3a2..." version 0 modifiedPaths "status"
This isn't a random bug. It’s a symptom of high-traffic scenarios, such as an e-commerce flash sale where 100+ requests per second attempt to update the same inventory record. While your local environment feels stable, the production race conditions are causing Mongoose to reject valid updates.
The Root Cause: Optimistic ConcurrencyMongoose manages document consistency using a property called __v (the version key). This implements Optimistic Concurrency Control. When you fetch a document using findById, Mongoose notes its current version, for example, __v: 0. When you eventually call doc.save(), Mongoose doesn't just filter by ID. It sends a specific query to MongoDB:
db.collection.updateOne(
{ _id: "65f3a2...", __v: 0 },
{ $set: { status: "shipped" }, $inc: { __v: 1 } }
)
If a separate process updated that same document just 10 milliseconds earlier, the __v in the database is now 1. Your update query, still looking for __v: 0, fails to find a match. Mongoose detects that zero documents were modified and throws the VersionError to prevent you from overwriting data you haven't seen.
Identifying the Conflict PatternCheck your service layer for this specific sequence:
- Fetch:
const doc = await Model.findById(id);- Logic: Perform CPU-intensive tasks or await other API calls.- Mutate:doc.status = 'processed';- Save:await doc.save();The longer the gap between step 1 and step 4, the higher the risk. If two requests start step 1 simultaneously, they both hold__v: 0. The first to reach the finish line wins; the second one crashes.
Proven Strategies to Fix VersionError### Option 1: Use Atomic Updates for Simple ChangesIf you don't rely on pre('save') hooks or complex schema validation, skip the fetch-then-save cycle. Use findOneAndUpdate or updateOne. These commands execute directly on the database and ignore Mongoose's internal versioning by default.
// Fast and collision-proof
await Model.updateOne(
{ _id: id },
{ $set: { status: 'shipped' } }
);
Why this works: It removes the "read-modify-write" cycle. It's a single operation that succeeds regardless of what happened a millisecond prior.
Option 2: Implement a Retry WrapperWhen your business logic is too complex to move out of .save(), you must handle the conflict gracefully. Catch the error, refresh the data, and try again. A simple 3-attempt retry loop often solves 99% of concurrency spikes.
async function safeUpdate(id, newStatus, retries = 3) {
for (let attempt = 1; attempt setTimeout(res, 50 * attempt));
continue;
}
throw error;
}
}
}
Option 3: Enable the 'optimisticConcurrency' OptionMongoose 5.10+ introduced a built-in way to handle this at the schema level. By setting optimisticConcurrency: true, Mongoose will automatically add the version check to all save operations, but you still need to catch and handle the resulting errors in your application code.
Testing the FixYou can simulate a race condition locally using Promise.all to trigger simultaneous updates on the same ID:
const doc = await Order.create({ status: 'pending' });
// Fire two updates at once
try {
await Promise.all([
safeUpdate(doc._id, 'shipped'),
safeUpdate(doc._id, 'delivered')
]);
console.log('Handled concurrent updates successfully.');
} catch (err) {
console.error('Update failed:', err.message);
}