mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Argument "docs" must be an array of documents

Error message

Argument "docs" must be an array of documents

What it means

Thrown by Collection.insertMany when its first argument is not an array. The method's contract requires ReadonlyArray<OptionalUnlessRequiredId<TSchema>>, so a non-array is a programming error and raises a MongoInvalidArgumentError before any I/O. It fails fast to give a clear message rather than a confusing bulk error.

Solutions

1. Wrap the document(s) in an array: insertMany([doc]).
2. If you have a single document, use insertOne instead.
3. Add an Array.isArray guard before the call when the source is dynamic.
4. Type the variable explicitly so TypeScript catches it at compile time.

Example fix

// before
await collection.insertMany({ a: 1 });

// after
await collection.insertMany([{ a: 1 }]);

if (!Array.isArray(docs)) {
  throw new TypeError('docs must be an array');
}
await collection.insertMany(docs);

function isDocArray(v: unknown): v is Record<string, unknown>[] {
  return Array.isArray(v) && v.every(d => d != null && typeof d === 'object' && !Array.isArray(d));
}

When it happens

Trigger: Fires at src/collection.ts:317 when `!Array.isArray(docs)`. Happens if a caller passes a single document object, a generator, a Set, undefined, or null to insertMany.

Common situations: Passing a single doc instead of [doc]; destructuring or spreading gone wrong; feeding a Map/Set; passing undefined because a variable was never assigned; refactoring from insertOne without wrapping in an array.

Related errors

• Argument "operations" must be an array of documents
• Argument "pipeline" must be an array of aggregation stages
• Collection.insertMany() cannot be called with an array that…
• Missing required callback parameter
• No client bulk write models were provided.

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

Appendix: source

Thrown at src/collection.ts:317

        resolveOptions(this, options)
      ) as TODO_NODE_3286
    );
  }

  /**
   * Inserts an array of documents into MongoDB. If documents passed in do not contain the **_id** field,
   * one will be added to each of the documents missing it by the driver, mutating the document. This behavior
   * can be overridden by setting the **forceServerObjectId** flag.
   *
   * @param docs - The documents to insert
   * @param options - Optional settings for the command
   */
  async insertMany(
    docs: ReadonlyArray<OptionalUnlessRequiredId<TSchema>>,
    options?: BulkWriteOptions
  ): Promise<InsertManyResult<TSchema>> {
    if (!Array.isArray(docs)) {
      throw new MongoInvalidArgumentError('Argument "docs" must be an array of documents');
    }
    options = resolveOptions(this, options ?? {});

    const acknowledged = WriteConcern.fromOptions(options)?.w !== 0;

    try {
      const res = await this.bulkWrite(
        docs.map(doc => ({ insertOne: { document: doc } })),
        options
      );
      return {
        acknowledged,
        insertedCount: res.insertedCount,
        insertedIds: res.insertedIds
      };
    } catch (err) {
      if (err && err.message === 'Operation must be an object with an operation key') {
        throw new MongoInvalidArgumentError(

View on GitHub (pinned to dce7939f86)