mongodb/node-mongodb-native · error · MongoInvalidArgumentError

MongoClient bulkWrite does not currently support automatic…

Error message

MongoClient bulkWrite does not currently support automatic encryption.

What it means

MongoClient.bulkWrite (src/mongo_client.ts:575) is the client-level bulk write API (server 8.0+). It explicitly refuses to run when the client has an autoEncrypter configured, throwing MongoInvalidArgumentError, because automatic encryption is not implemented for the client-level bulk write path. This is a product limitation, not a transient condition.

Solutions

  1. Use per-collection collection.bulkWrite() instead, which supports auto-encryption.
  2. Perform client.bulkWrite on a separate MongoClient that does not have autoEncryption configured (only if the data does not require encryption).
  3. If encryption is required, encrypt fields explicitly or route through a collection-level API.

Example fix

// before
const client = new MongoClient(uri, { autoEncryption: {...} });
await client.bulkWrite([{ insertOne: { namespace: 'db.coll', document: {...} } }]);
// after
await client.db('db').collection('coll').bulkWrite([{ insertOne: { document: {...} } }]);
Defensive patterns

Strategy: validation

Validate before calling

function assertBulkWriteCompatible(autoEncrypter) {
  if (autoEncrypter) {
    throw new Error('client.bulkWrite is unavailable with autoEncryption; use collection.bulkWrite');
  }
}
// or: detect at config time
if (clientOptions.autoEncryption) delete clientOptions._useClientBulkWrite;

Type guard

function clientHasAutoEncryption(client: MongoClient): boolean {
  return (client as any).autoEncrypter != null;
}

Try / catch

try {
  await client.bulkWrite(models);
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /automatic encryption/.test(e.message)) {
    // route to collection.bulkWrite instead
  } else throw e;
}

Prevention

When it happens

Trigger: Constructing new MongoClient(uri, { autoEncryption: {...} }) and then calling client.bulkWrite(models). Any attempt to combine CSFLE auto-encryption with the client-level bulkWrite helper.

Common situations: Enabling CSFLE globally on the client and then trying the new client.bulkWrite API for cross-collection writes. Migrating per-collection bulkWrite code to client.bulkWrite without realizing autoEncryption is incompatible.

Related errors

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

Appendix: source

Thrown at src/mongo_client.ts:580

    return this.s.bsonOptions;
  }

  get timeoutMS(): number | undefined {
    return this.s.options.timeoutMS;
  }

  /**
   * Executes a client bulk write operation, available on server 8.0+.
   * @param models - The client bulk write models.
   * @param options - The client bulk write options.
   * @returns A ClientBulkWriteResult for acknowledged writes and ok: 1 for unacknowledged writes.
   */
  async bulkWrite<SchemaMap extends Record<string, Document> = Record<string, Document>>(
    models: ReadonlyArray<ClientBulkWriteModel<SchemaMap>>,
    options?: ClientBulkWriteOptions
  ): Promise<ClientBulkWriteResult> {
    if (this.autoEncrypter) {
      throw new MongoInvalidArgumentError(
        'MongoClient bulkWrite does not currently support automatic encryption.'
      );
    }
    // We do not need schema type information past this point ("as any" is fine)
    return await new ClientBulkWriteExecutor(
      this,
      models as any,
      resolveOptions(this, options)
    ).execute();
  }

  /**
   * An optional method to verify a handful of assumptions that are generally useful at application boot-time before using a MongoClient.
   * For detailed information about the connect process see the MongoClient.connect static method documentation.
   *
   * @param url - The MongoDB connection string (supports `mongodb://` and `mongodb+srv://` schemes)
   * @param options - Optional configuration options for the client
   *

View on GitHub (pinned to dce7939f86)