mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Client bulk write operation ${name} of length ${buffer.lengt

Error message

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

What it means

Thrown by validateBufferSize() when a single serialized operation or nsInfo entry exceeds the server's maxBsonObjectSize (16 MiB by default). This is per-document, not per-batch: one model's filter/update/document alone is too large. MongoInvalidArgumentError fires before the command is sent.

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 3366c21a63)

Solutions

1. Reduce the size of the offending document — store large binaries in GridFS instead of inline.
2. Split oversized arrays/embedded data across multiple documents or external collections.
3. If the server genuinely allows a larger maxBsonObjectSize, confirm the value and that you are not exceeding it; otherwise the document must shrink.

Example fix

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

// after
const bucket = new GridFSBucket(db);
const id = await bucket.uploadBytes('file', hugeBuffer);
await client.bulkWrite([{
  namespace: 'db.files',
  name: 'insertOne',
  document: { fileId: id, name: 'file' }
}]);

const MAX = 16 * 1024 * 1024;
function approxDocBytes(doc) { return JSON.stringify(doc).length; }
if (models.some(m => approxDocBytes(m.document ?? m.update ?? m.filter) > MAX)) {
  throw new Error('Model exceeds 16MB');
}

When it happens

Trigger: An insertOne document, an updateMany update document, or a filter that individually serializes to more than 16 MiB. Large embedded binary blobs, huge arrays, or oversized $search/$lookup payloads in a single model.

Common situations: Storing large media or base64 blobs in a single document; very large IN-style filter arrays; embedding large nested structures; migrating oversized documents via bulk write.

Related errors

• Could not serialize operation to BSON
• Could not serialize ns info to BSON
• Client bulk write update models must only contain atomic mod
• Client bulk write replace models must not contain atomic mod
• No client bulk write models were provided.

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