mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Client bulk write operation

Error message

Client bulk write operation ${name} of length ${buffer.length} exceeds the max bson object size of ${maxBsonObjectSize}

What it means

Thrown when a single serialized client bulk write operation (or its nsInfo document) is larger than the server's maxBsonObjectSize (typically 16 MB). Unlike batch-splitting which the driver does automatically, a single oversized document cannot be sent at all, so the driver rejects it up front.

Solutions

1. Move large binaries to GridFS (bucket.openUploadStream) or an object store and keep only a reference in the document.
2. Split the document into smaller pieces across collections and reference by _id.
3. Confirm the server's limit with hello().maxBsonObjectSize and design inserts to stay well under it.

Example fix

// before
await client.bulkWrite([{
  insertOne: { namespace: 'db.files', document: { name, data: hugeBuffer } }
}]);

// after
const bucket = new mongoose.mongo.GridFSBucket(db);
await bucket.openUploadStream(name).end(hugeBuffer);

import { serialize } from 'bson';
const MAX = 16 * 1024 * 1024; // or fetch from server hello
const serialized = serialize(document);
if (serialized.length > MAX) {
  throw new Error(`Document is ${serialized.length} bytes; exceeds ${MAX}`);
}

try {
  await client.bulkWrite(models);
} catch (e) {
  if (/exceeds the max bson object size/.test(e.message)) {
    // move payload to GridFS or split the document
  }
}

When it happens

Trigger: An insertOne document, an updateMany update document, or a replaceOne replacement document whose serialized form exceeds maxBsonObjectSize. Often an inline binary blob, an embedded image, or a deeply nested array.

Common situations: Storing files inline instead of GridFS; embedding large base64 payloads; pre-encoding PDFs/images as BSON BinData that grows past 16 MB; analytics pipelines that aggregate into a single huge doc.

Related errors

• Could not serialize ns info to BSON
• Could not serialize operation to BSON
• Argument "operations" must be an array of documents
• Attempt to access memory outside buffer bounds: buffer…
• Binary type with subtype 0x02 contains too long binary size

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/c8caa67d4130d8a1. Report an issue: GitHub.

Appendix: source

Thrown at src/operations/client_bulk_write/command_builder.ts:238

    }
    // Add let if it was present in the options.
    if (this.options.let) {
      command.let = this.options.let;
    }

    // we check for undefined specifically here to allow falsy values
    // eslint-disable-next-line no-restricted-syntax
    if (this.options.comment !== undefined) {
      command.comment = this.options.comment;
    }

    return command;
  }
}

function validateBufferSize(name: string, buffer: Uint8Array, maxBsonObjectSize: number) {
  if (buffer.length > maxBsonObjectSize) {
    throw new MongoInvalidArgumentError(
      `Client bulk write operation ${name} of length ${buffer.length} exceeds the max bson object size of ${maxBsonObjectSize}`
    );
  }
}

/** @internal */
export interface ClientInsertOperation {
  insert: number;
  document: OptionalId<Document>;
}

/**
 * Build the insert one operation.
 * @param model - The insert one model.
 * @param index - The namespace index.
 * @returns the operation.
 */
export const buildInsertOneOperation = (

View on GitHub (pinned to dce7939f86)