{"record":{"id":"c8caa67d4130d8a1","repo":"mongodb/node-mongodb-native","slug":"client-bulk-write-operation-name-of-length-bu","errorCode":null,"errorMessage":"Client bulk write operation ${name} of length ${buffer.length} exceeds the max bson object size of ${maxBsonObjectSize}","messagePattern":"Client bulk write operation (.+?) of length (.+?) exceeds the max bson object size of (.+?)","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/operations/client_bulk_write/command_builder.ts","lineNumber":238,"sourceCode":"    }\n    // Add let if it was present in the options.\n    if (this.options.let) {\n      command.let = this.options.let;\n    }\n\n    // we check for undefined specifically here to allow falsy values\n    // eslint-disable-next-line no-restricted-syntax\n    if (this.options.comment !== undefined) {\n      command.comment = this.options.comment;\n    }\n\n    return command;\n  }\n}\n\nfunction validateBufferSize(name: string, buffer: Uint8Array, maxBsonObjectSize: number) {\n  if (buffer.length > maxBsonObjectSize) {\n    throw new MongoInvalidArgumentError(\n      `Client bulk write operation ${name} of length ${buffer.length} exceeds the max bson object size of ${maxBsonObjectSize}`\n    );\n  }\n}\n\n/** @internal */\nexport interface ClientInsertOperation {\n  insert: number;\n  document: OptionalId<Document>;\n}\n\n/**\n * Build the insert one operation.\n * @param model - The insert one model.\n * @param index - The namespace index.\n * @returns the operation.\n */\nexport const buildInsertOneOperation = (","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/operations/client_bulk_write/command_builder.ts#L220-L256","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Move large binaries to GridFS (bucket.openUploadStream) or an object store and keep only a reference in the document.","Split the document into smaller pieces across collections and reference by _id.","Confirm the server's limit with hello().maxBsonObjectSize and design inserts to stay well under it."],"exampleFix":"// before\nawait client.bulkWrite([{\n  insertOne: { namespace: 'db.files', document: { name, data: hugeBuffer } }\n}]);\n\n// after\nconst bucket = new mongoose.mongo.GridFSBucket(db);\nawait bucket.openUploadStream(name).end(hugeBuffer);","handlingStrategy":"validation","validationCode":"import { serialize } from 'bson';\nconst MAX = 16 * 1024 * 1024; // or fetch from server hello\nconst serialized = serialize(document);\nif (serialized.length > MAX) {\n  throw new Error(`Document is ${serialized.length} bytes; exceeds ${MAX}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await client.bulkWrite(models);\n} catch (e) {\n  if (/exceeds the max bson object size/.test(e.message)) {\n    // move payload to GridFS or split the document\n  }\n}","preventionTips":["Store large binaries in GridFS or object storage; keep only references inline.","Query hello().maxBsonObjectSize at startup to size payloads correctly."],"tags":["bulk-write","bson","size-limit"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}