Merge pull request #15743 from Mario5T/master

Added a new FAQ entry right before the final “Something to add?” sect…

Author: vkarpov15

docs/faq.md

@@ -430,6 +430,51 @@ await query.clone(); // Works
 Note: Mongoose v7+ no longer supports callbacks. If you're seeing duplicate queries in older code,
 it may be due to mixing callbacks and promises, which is no longer possible in current versions.
 
+<hr id="divergent-array-error" />
+
+<a class="anchor" href="#divergent-array-error">**Q**</a>. What does `DivergentArrayError` mean and how do I fix it?
+
+**A**. Mongoose throws `DivergentArrayError` when you call `document.save()` to update an array that was only partially loaded, for example:
+
+* the array was selected using an `$elemMatch` projection
+* the array was populated using `populate()` with `skip`, `limit`, query conditions, or options that exclude `_id`
+* the save would result in MongoDB performing a `$set` or `$pop` of the entire array
+
+Because only part of the array is in memory, Mongoose can't safely reconstruct the full array to send back to MongoDB without risking data loss, so it throws `DivergentArrayError` instead.
+
+For example:
+
+```javascript
+const doc = await BlogPost.findOne(
+  { _id },
+  { comments: { $elemMatch: { flagged: true } } }
+);
+
+doc.comments[0].text = 'Updated';
+await doc.save(); 
+```
+
+To fix this error, either:
+
+(1) Load the full array before modifying and saving:
+
+```javascript
+const doc = await BlogPost.findById(_id); 
+doc.comments.id(commentId).text = 'Updated';
+await doc.save();
+```
+
+(2) Or use `updateOne()` / `updateMany()` with positional operators or `arrayFilters` so MongoDB can update the array atomically without requiring the full array on the document:
+
+```javascript
+await BlogPost.updateOne(
+  { _id, 'comments._id': commentId },
+  { $set: { 'comments.$.text': 'Updated' } }
+);
+```
+
+The same guidance applies if you populated an array with `skip`, `limit`, query conditions, or excluded `_id`: avoid calling `save()` to update that partially loaded array; instead, re-query without those options or use an update operation as shown above.
+
 <hr id="add_something" />
 
 **Something to add?**

lib/error/divergentArray.js

@@ -23,8 +23,8 @@ class DivergentArrayError extends MongooseError {
             + 'the entire array is not supported. The following '
             + 'path(s) would have been modified unsafely:\n'
             + '  ' + paths.join('\n  ') + '\n'
-            + 'Use Model.updateOne() to update these arrays instead.';
-    // TODO write up a docs page (FAQ) and link to it
+            + 'Use Model.updateOne() to update these arrays instead. '
+            + 'See https://mongoosejs.com/docs/faq.html#divergent-array-error for more information.';
     super(msg);
   }
 }