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 UnorderedBulkOperation.addToOperationsList() when a single operation's serialized BSON size is >= the server's maxBsonObjectSize (typically 16MB). Identical semantics to the ordered variant; the unordered batch type just routes through a different addToOperationsList implementation.

Source

Thrown at src/bulk/unordered.ts:60

    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}`
      );
    }

    // Holds the current batch
    this.s.currentBatch = undefined;
    // Get the right type of batch
    if (batchType === BatchType.INSERT) {
      this.s.currentBatch = this.s.currentInsertBatch;
    } else if (batchType === BatchType.UPDATE) {
      this.s.currentBatch = this.s.currentUpdateBatch;
    } else if (batchType === BatchType.DELETE) {
      this.s.currentBatch = this.s.currentRemoveBatch;
    }

    const maxKeySize = this.s.maxKeySize;

    // Create a new batch object if we don't have a current one

View on GitHub (pinned to 3366c21a63)

Solutions

1. Move large blobs to GridFS or external storage and keep references in the document.
2. Split or chunk the document.
3. Verify the server's reported maxBsonObjectSize to know the real ceiling.

Example fix

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

// after
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 very large document via unordered bulk.insert(). Updating with a multi-megabyte $set value in an unordered batch.

Common situations: Loading large media/log payloads inline; migrating data from a store without a 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
• Update document requires atomic operators

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