Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

updateOne() runs without an error but the document does not change

ErrorUpdate document requires atomic operators

Short 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.

  • Applies to MongoDB Node.js driver (current docs), mongosh, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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);
  2. 2Match what you see, then jump to its fix

    1. 1MongoInvalidArgumentError: Update document requires atomic operatorsThe update document has no update operatorFix
    2. 2matchedCount: 0 and modifiedCount: 0, with no errorThe filter matches no documentFix
    3. 3matchedCount: 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. 4The 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

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.js

Confirmed by github.com

Did this fix it?

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

Did this fix it?

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

Did this fix it?

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 await

2Fix

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.js

Confirmed by mongodb.com

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.