mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Operation passed in cannot be an Array

Error message

Operation passed in cannot be an Array

What it means

Thrown by UnorderedBulkOperation.addToOperationsList() when the operation document passed to a bulk write method is a JavaScript Array instead of a plain object. Each bulk operation (insert, update, delete) must be a single BSON document; an array is not a valid operation shape. This is a MongoInvalidArgumentError.

Solutions

1. Ensure each call to bulk.insert() receives a single document object, not an array
2. If you have an array of documents, loop and call insert for each: docs.forEach(d => bulk.insert(d))
3. Use collection.insertMany(docs) instead of bulk operations if you have a pre-built array of insert documents
4. Add a runtime type check (Array.isArray(doc)) before calling bulk methods to catch this in JavaScript code

Example fix

// before
const docs = [{ a: 1 }, { a: 2 }];
bulk.insert(docs); // passes the array itself

// after
for (const doc of docs) {
  bulk.insert(doc); // passes each document individually
}

// Before calling bulk.insert(doc)
if (Array.isArray(doc)) {
  throw new TypeError('Bulk operation document must not be an array; pass individual documents');
}
bulk.insert(doc);

function isBulkOperationDoc(doc: unknown): doc is Record<string, unknown> {
  return typeof doc === 'object' && doc !== null && !Array.isArray(doc);
}

try {
  bulk.insert(doc);
} catch (error) {
  if (error instanceof MongoInvalidArgumentError && error.message.includes('cannot be an Array')) {
    // Handle array misuse: iterate and insert individually
  }
  throw error;
}

When it happens

Trigger: Calling bulk.insert([...]) with an array instead of a single document object, or manually calling addToOperationsList() with an array-typed document. More commonly reached when a caller iterates over a list and forgets to spread or destructure, passing the array container rather than an element.

Common situations: Looping over an array of documents and accidentally passing the outer array instead of an individual element; migrating from insertMany (which takes an array) to the bulk API (which takes individual documents); JavaScript code that bypasses TypeScript type safety at runtime.

Related errors

• Argument "operations" must be an array of documents
• Operation must be an object with an operation key
• Argument "docs" must be an array of documents
• Argument "pipeline" must be an array of aggregation stages
• Bulk find operation must specify a selector

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

Appendix: source

Thrown at src/bulk/unordered.ts:103

      // New batch if we exceed the max batch op size
      this.s.currentBatch.size + 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.currentBatch.size > 0 &&
        this.s.currentBatch.sizeBytes + maxKeySize + bsonSize >= this.s.maxBatchSizeBytes) ||
      // New batch if the new op does not have the same op type as the current batch
      this.s.currentBatch.batchType !== batchType
    ) {
      // Save the batch to the execution stack
      this.s.batches.push(this.s.currentBatch);

      // Create a new batch
      this.s.currentBatch = new Batch(batchType, this.s.currentIndex);
    }

    // We have an array of documents
    if (Array.isArray(document)) {
      throw new MongoInvalidArgumentError('Operation passed in cannot be an Array');
    }

    this.s.currentBatch.operations.push(document);
    if (buffer != null) this.s.currentBatch.serializedOperations.push(buffer);
    this.s.currentBatch.originalIndexes.push(this.s.currentIndex);
    this.s.currentIndex = this.s.currentIndex + 1;

    // Save back the current Batch to the right type
    if (batchType === BatchType.INSERT) {
      this.s.currentInsertBatch = this.s.currentBatch;
      this.s.bulkResult.insertedIds.push({
        index: this.s.bulkResult.insertedIds.length,
        _id: (document as Document)._id
      });
    } else if (batchType === BatchType.UPDATE) {
      this.s.currentUpdateBatch = this.s.currentBatch;
    } else if (batchType === BatchType.DELETE) {
      this.s.currentRemoveBatch = this.s.currentBatch;

View on GitHub (pinned to dce7939f86)