Atlas error: BSON document exceeds the 16MB limit

TL;DR: Documents have a hard 16MB cap. Hitting it means the schema needs chunking, references, or GridFS, not a bigger limit. Confirm Check which write path creates the giant: unbounded arrays (event logs, comments, history appended forever), embedded base64 blobs, or denormalized copies that grew. Verify Insert the previously failing payload through the new shape.

The fix

Document too large

Full text: BSONObjectTooLarge or document too large. MongoDB caps a single document at 16MB. There is no option to raise it.

Confirm

Check which write path creates the giant: unbounded arrays (event logs, comments, history appended forever), embedded base64 blobs, or denormalized copies that grew.

Fix, pick one

• Chunk the array into separate documents (one document per page of N items, or one document per array element with a parent reference).
• Store blobs in GridFS or object storage and keep only a pointer in the document.
• Reference instead of embed for unbounded one-to-many relationships.

Verify

Insert the previously failing payload through the new shape. Also add a guard: validate array length or payload size in application code so the next growth spurt fails fast with your error, not the driver's.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Atlas error.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current Atlas behavior.

The 16MB BSON document size limit is a fixed server constraint documented in the MongoDB limits reference; schema redesign guidance follows MongoDB data modeling practices, verified 2026-09-26.