updateOne() runs without an error but the document does not change
Update document requires atomic operatorsShort answer
updateOne() reports what it did in its result. Log result.matchedCount and result.modifiedCount first. A matchedCount of 0 means your filter found nothing. An error about atomic operators means the update document lacks $set or another operator. A matchedCount of 1 and a document you expected to change twice means updateOne only touches the first match.
Fix it fast
1Find out which cause you have
Print the whole result of the call. It carries the counters that tell the causes apart: how many documents matched the filter, and how many were changed.
const result = await users.updateOne(filter, update); console.log(filter, update, result);2Match what you see, then jump to its fix
- 1
MongoInvalidArgumentError: Update document requires atomic operatorsThe update document has no update operatorFix - 2
matchedCount: 0 and modifiedCount: 0, with no errorThe filter matches no documentFix - 3
matchedCount: 1 although several documents fit the filter; the rest stay as they wereMore than one document should change, and updateOne stops after the firstFix - 4
The counters are never printed, or the script closes the client before the update has finishedThe returned promise is not awaited, so the script ends or the client closes firstFix
- 1
What does the error look like?
Update document requires atomic operators{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0 }MongoInvalidArgumentError
Cause 1 of 4
The update document has no update operator
1Check
The driver checks the second argument of updateOne() before it sends anything. The docs say the top level of an update document holds update operators such as $set, $inc, $rename, $unset or $mul. A plain object of new field values is a replacement document, which updateOne() does not take.
grep -rn "updateOne(" src/2Fix
Wrap the fields you want to change in $set, or use another update operator. If you really want to swap the whole document, use replaceOne() instead.
// wrong: await users.updateOne({ _id: id }, { plan: 'pro' });
await users.updateOne({ _id: id }, { $set: { plan: 'pro' } });3Verify
Run the call again. It returns a result object and no longer throws.
node scripts/update-plan.jsConfirmed by github.com
Cause 2 of 4
The filter matches no document
1Check
The docs say that when an update fails to match any document, it makes no changes, and no error is raised. The result then shows matchedCount 0. Compare the filter with what is stored: the field name, its spelling and the type of the value.
// in mongosh
db.users.findOne({ email: "a@example.com" })2Fix
Correct the filter so it names the stored field and value. If the right behaviour is to create the document when it is missing, set upsert: true, which inserts a new document when nothing matches.
await users.updateOne(
{ email: 'a@example.com' },
{ $set: { plan: 'pro' } },
{ upsert: true }
);3Verify
The result shows matchedCount 1, or an upsertedId when a document was created.
const result = await users.updateOne({ email: 'a@example.com' }, { $set: { plan: 'pro' } });
console.log(result.matchedCount, result.modifiedCount, result.upsertedId);Confirmed by mongodb.com
Cause 3 of 4
More than one document should change, and updateOne stops after the first
1Check
The manual says updateOne() finds the first document that matches the filter and applies the change to that one only, even if more match. After the call, run the same filter with findOne in mongosh. If it still returns a document, the filter matched more than one.
// in mongosh
db.users.findOne({ plan: "free" })2Fix
Use updateMany() for a filter that should change every match.
const result = await users.updateMany({ plan: 'free' }, { $set: { plan: 'pro' } });
console.log(result.matchedCount, result.modifiedCount);3Verify
The same findOne now returns null, because no document matches the filter any more.
// in mongosh
db.users.findOne({ plan: "free" })Confirmed by mongodb.com
Cause 4 of 4
The returned promise is not awaited, so the script ends or the client closes first
1Check
updateOne() returns a promise. The driver's own example awaits it inside an async function and closes the client in a finally block, after the awaited call has finished.
grep -rn "updateOne(" src/ | grep -v await2Fix
Await the call, and close the client only after every await has completed.
async function run() {
try {
// ... get the collection, then:
const result = await users.updateOne(filter, { $set: { plan: 'pro' } });
console.log(result.modifiedCount);
} finally {
await client.close();
}
}
run().catch(console.dir);3Verify
Run the script. The counters print before the process exits.
node scripts/update-plan.jsConfirmed by mongodb.com
How do I stop it coming back?
- Always read matchedCount and modifiedCount after a write and treat matchedCount 0 as a bug when you expect a match.
- Keep one small helper for updates in your data layer, so update documents are always written with an operator.
- Use updateMany() on purpose when the filter can match several documents, and say so in the function name.
- Await every driver call and close the client in a finally block.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
Mongoose says a required path is missing when you save a document
Path `name` is required.
The required validator fails when the value is undefined or null at save time.
3 causes, each with a fixDatabases
Node.js in Docker Compose cannot find mysql2/promise
The app works on the host but fails after docker compose up
mysql2/promise is a path inside the mysql2 package.
2 causes, each with a fixDatabases
Elasticsearch rejects requests with circuit_breaking_exception: Data too large
circuit_breaking_exception with a reason that contains Data too large
A circuit_breaking_exception with 'Data too large' means Elasticsearch refused work to protect a node's JVM heap.
3 causes, each with a fixDatabases
JupyterLab cannot determine its build status without Node.js
Could not determine jupyterlab build status without nodejs
JupyterLab itself runs without Node.js, but source extensions need Node.js to rebuild it.
3 causes, each with a fixDatabases
Mongoose cannot sign in to MongoDB Atlas: bad auth, authentication failed
MongoError: bad auth Authentication failed.
Authentication failed means the server rejected the user in your connection string.
3 causes, each with a fixDatabases
MongoDB says duplicate key, but the value is null
MongoServerError: E11000 duplicate key error
A unique index in MongoDB stores a missing field as null, and only one null entry is allowed.
3 causes, each with a fix