MongoDB 9: Unknown modifier, expected a valid modifier

What it means

A classic update document is made of update operators, each holding the fields it changes: { $set: { qty: 2 }, $inc: { views: 1 } }. MongoDB reads each top-level key as an operator. One of yours isn’t on its list, so it refused the update with code 9, FailedToParse, and changed nothing.

The message quotes the key it didn’t recognise: Unknown modifier: $sett. The second half is a hint: an update can also be an array, a pipeline, where aggregation expressions are allowed.

The update operators are: $set, $unset, $inc, $mul, $min, $max, $rename, $setOnInsert, $currentDate, $push, $pull, $pullAll, $addToSet, $pop and $bit. ($each, $position, $slice and $sort are modifiers used inside $push and $addToSet.)

Common causes

A typo or the wrong case. Operators are case-sensitive: $Inc, $addtoset and $sett are all unknown.
An aggregation operator in a classic update: $concat, $cond, $add, $size. They work in a pipeline update, not as top-level update keys.
A field next to operators: { $set: { qty: 1 }, name: "x" } reports Unknown modifier: name.
An operator that belongs inside another one: $each or $slice at the top level instead of inside $push.

A document with no operators at all is a different mistake: drivers refuse it before sending, with Update document requires atomic operators (use replaceOne to replace a whole document).

How to fix it

Fix the operator name

Compare the key in the message with the list above. Most of the time it’s a typo or a capital letter: $inc, $addToSet.

Use a pipeline for expressions

To compute a value from other fields, wrap the update in an array. In a pipeline, $set takes aggregation expressions:

db.p.updateOne(
  { sku: "A-1" },
  [{ $set: { name: { $concat: ["$name", " (old)"] } } }]
)

Put every field inside an operator

db.p.updateOne({ sku: "A-1" }, { $set: { qty: 1, name: "x" } })

Put modifiers inside their operator

db.p.updateOne(
  { sku: "A-1" },
  { $push: { tags: { $each: ["blue", "green"], $slice: -10 } } }
)

Reproduce it

MongoDB 8.0.32, mongosh 2.12.0:

db.items.updateOne({ _id: 1 }, { $sett: { qty: 2 } })

MongoServerError: Unknown modifier: $sett. Expected a valid update modifier or pipeline-style update specified as an array

The error’s code was 9. The other cases, with the same second sentence:

MongoServerError: Unknown modifier: $concat. …
MongoServerError: Unknown modifier: $addtoset. …
MongoServerError: Unknown modifier: $Inc. …
MongoServerError: Unknown modifier: name. …
MongoServerError: Unknown modifier: $size. …

$Inc came beside a valid $set, and the $set wasn’t applied either. An update with no operators ({ qty: 2 }) stopped in mongosh’s driver:

MongoInvalidArgumentError: Update document requires atomic operators

The pipeline form with $concat turned Lamp 2 into Lamp 2 (old), and the $push with $each and $slice added both tags.

In Inlet

Queries use mongosh syntax, so you can run the corrected updateOne (classic or pipeline) and look at the document in the inspector afterwards. A refused update shows the server’s message, with the unknown key in it. Inlet’s document editor writes its own updates for the fields you change.

Unknown modifier: $… Expected a valid update modifier or pipeline-style update