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