BSONObj size is invalid. Size must be between 0 and 16793600(16MB)

What it means

MongoDB stores each document as BSON, and a BSON document can be at most 16 MB (16,777,216 bytes). The limit applies to what you insert, to the document an update would leave behind, and to each document an aggregation produces. Anything bigger is refused with code 10334, BSONObjectTooLarge. Nothing is written.

The wording depends on where the limit was hit:

The slightly larger numbers in some messages (16793600, 16809984) are internal limits with room for the command around a document; the limit for the document itself is 16 MB. First element names the first field of the document that was too large, often its _id, which tells you which one it was.

Common causes

1. An array that grows without end: comments, events, log lines or order history $pushed into one document.
2. Files or images stored in a field as binary or base64 text.
3. A $group with $push (or $addToSet) that gathers too many values into one group, often _id: null, which puts everything in a single document.
4. $lookup that pulls many large documents into an array field.
5. A large import row, for example a JSON file whose top level is one huge object.

How to fix it

Find the largest documents

db.posts.aggregate([
  { $project: { size: { $bsonSize: "$$ROOT" } } },
  { $sort: { size: -1 } },
  { $limit: 5 }
])

$bsonSize (MongoDB 4.4 and later) gives each document’s size in bytes. In mongosh, bsonsize(doc) measures one you have in hand.

Move growing arrays into their own collection

Store each comment or event as its own document with a reference back (postId), and index that field. If you need some of them inside the parent (the latest ten, say), keep a capped copy with $push and $slice:

db.posts.updateOne(
  { _id: postId },
  { $push: { recentComments: { $each: [comment], $slice: -10 } } }
)

Store files in GridFS or object storage

GridFS splits a file into chunks of 255 KB stored as separate documents, so files can be any size. Drivers include it (GridFSBucket in Node.js). Or store files in object storage and keep the URL in MongoDB.

Keep pipeline outputs small

Group into many documents rather than one, push only the fields you need, or count instead of collecting:

db.orders.aggregate([{ $group: { _id: "$customer", n: { $sum: 1 } } }])

To write a large result somewhere, $out or $merge it into a collection instead of building one document.

Reproduce it

MongoDB 8.0.32 and mongosh 2.12.0. A document of 9 MB, then a $set that adds another 9 MB string:

db.big.insertOne({ _id: 2, body: "x".repeat(9 * 1024 * 1024) })
db.big.updateOne({ _id: 2 }, { $set: { copy: "y".repeat(9 * 1024 * 1024) } })

MongoServerError: BSONObj size: 18874404 (0x1200024) is invalid. Size must be between 0 and 16793600(16MB) First element: _id: 2

The error’s code was 10334. A pipeline update copying body into copy gave the same message. An insert of a document 125 bytes over 16 MB:

MongoServerError: object to insert too large. size in bytes: 16777341, max size: 16777216

A 16.5 MB string in one insert:

MongoServerError[BSONObjectTooLarge]: BSONObj size: 17301638 (0x1080086) is invalid. Size must be between 0 and 16809984(16MB) First element: insert: "big"

A $project that doubled body (9 MB) in an aggregation:

MongoServerError[BSONObjectTooLarge]: PlanExecutor error during aggregation :: caused by :: BSONObj size: 18874398 (0x120001E) is invalid. Size must be between 0 and 16793600(16MB) First element: _id: 2

And $group with _id: null pushing four bodies of 6 to 9 MB:

MongoServerError[BSONObjectTooLarge]: BSON size limit hit while building Message. Size: 28311713 (0x1B000A1); maxSize: 16809984(16MB)

A 17 MB string failed before reaching the server, in mongosh and in the Node.js driver 6.20.0, with RangeError: The value of "offset" is out of range., from the library that encodes BSON. The $bsonSize query above listed the largest document first, at 16,777,141 bytes.

In Inlet

Inlet shows each document in the inspector, which handles long text, JSON and binary values, so you can see which field is growing. Queries use mongosh syntax, so the $bsonSize pipeline above runs in a query tab.