mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Document is larger than the maximum size ${this.s.maxBsonObj

Error message

Document is larger than the maximum size ${this.s.maxBsonObjectSize}

What it means

Thrown by OrderedBulkOperation.addToOperationsList() when a single operation's serialized BSON size is >= the server's maxBsonObjectSize (typically 16MB, learned from the server at handshake). The check fires before the op is added to a batch; oversized documents cannot be sent to MongoDB and must be reduced or stored differently (e.g. GridFS).

Source

Thrown at src/bulk/ordered.ts:46

    if (this.s.usingAutoEncryption) {
      bsonSize = BSON.calculateObjectSize(document, {
        checkKeys: false,
        ignoreUndefined: false
      } as any);
    } else {
      const bson = this.s.bsonOptions;
      buffer = BSON.serialize(document, {
        checkKeys: this.s.checkKeys,
        ignoreUndefined: bson.ignoreUndefined,
        serializeFunctions: bson.serializeFunctions
      });
      bsonSize = buffer.length;
    }

    // Throw error if the doc is bigger than the max BSON size
    if (bsonSize >= this.s.maxBsonObjectSize)
      // TODO(NODE-3483): Change this to MongoBSONError
      throw new MongoInvalidArgumentError(
        `Document is larger than the maximum size ${this.s.maxBsonObjectSize}`
      );

    // Create a new batch object if we don't have a current one
    if (this.s.currentBatch == null) {
      this.s.currentBatch = new Batch(batchType, this.s.currentIndex);
    }

    const maxKeySize = this.s.maxKeySize;

    // Check if we need to create a new batch
    if (
      // New batch if we exceed the max batch op size
      this.s.currentBatchSize + 1 >= this.s.maxWriteBatchSize ||
      // New batch if we exceed the maxBatchSizeBytes. Only matters if batch already has a doc,
      // since we can't sent an empty batch
      (this.s.currentBatchSize > 0 &&
        this.s.currentBatchSizeBytes + maxKeySize + bsonSize >= this.s.maxBatchSizeBytes) ||

View on GitHub (pinned to 3366c21a63)

Solutions

1. Reduce document size: store large blobs in GridFS or an object store and keep only a reference in the document.
2. Split the document or chunk the payload across multiple documents.
3. Confirm maxBsonObjectSize from the server (coll.s.db.client.s.options / hello response) to know your actual limit.

Example fix

// before
bulk.insert({ data: hugeBuffer }); // hugeBuffer > 16MB

// after
// store large content out-of-band, keep a reference
const id = await bucket.upload(hugeBuffer);
bulk.insert({ contentId: id, metadata: {...} });

import * as BSON from 'bson';
function assertUnderMaxSize(doc, maxBsonObjectSize = 16 * 1024 * 1024) {
  const size = BSON.serialize(doc).length;
  if (size >= maxBsonObjectSize) {
    throw new RangeError(`document serialized to ${size} bytes, exceeds ${maxBsonObjectSize}`);
  }
}

function isWithinBsonLimit(doc, maxBsonObjectSize = 16 * 1024 * 1024) {
  try {
    return BSON.serialize(doc).length < maxBsonObjectSize;
  } catch {
    return false;
  }
}

try {
  bulk.insert(doc);
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /larger than the maximum size/.test(e.message)) {
    // route to GridFS or chunk the document
  }
}

When it happens

Trigger: Inserting a document with a large embedded binary/text field via bulk.insert(). Updating with a multi-megabyte $set value. Pushing large arrays via $push.

Common situations: Loading large media or log blobs inline; serializing large nested structures; migrating from a store with no size limit.

Related errors

• Document is larger than the maximum size ${this.s.maxBsonObj
• Operation passed in cannot be an Array
• Could not serialize operation to BSON
• Could not serialize ns info to BSON
• Cannot request unacknowledged write concern and ordered writ

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/4ea40c398bec961a.json. Report an issue: GitHub.