mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Option "autoEncryption" must be specified

Error message

Option "autoEncryption" must be specified

What it means

The internal Encrypter class (src/encrypter.ts:20) requires options.autoEncryption to be an object. It is constructed by MongoClient when autoEncryption is configured; if the value is present but not an object (or the Encrypter is invoked without it), this MongoInvalidArgumentError is thrown. Typically this reflects a malformed autoEncryption setting rather than a missing one (a missing setting would not construct an Encrypter at all).

Solutions

1. Provide autoEncryption as an object with at least a keyVaultNamespace and kmsProviders, e.g. autoEncryption: { keyVaultNamespace: 'encryption.__keyVault', kmsProviders: { ... } }.
2. Remove the autoEncryption key entirely if you did not intend to enable CSFLE.
3. Validate the shape of autoEncryption before constructing the MongoClient.

Example fix

// before
const client = new MongoClient(uri, { autoEncryption: true });
// after
const client = new MongoClient(uri, {
  autoEncryption: {
    keyVaultNamespace: 'encryption.__keyVault',
    kmsProviders: { local: { key: localKey } }
  }
});

function validateAutoEncryption(opts) {
  if (opts.autoEncryption != null && typeof opts.autoEncryption !== 'object') {
    throw new TypeError('autoEncryption must be an object or omitted');
  }
  return opts;
}
const client = new MongoClient(uri, validateAutoEncryption(opts));

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

try {
  const client = new MongoClient(uri, opts);
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /autoEncryption/.test(e.message)) {
    // fix autoEncryption shape
  }
  throw e;
}

When it happens

Trigger: Passing autoEncryption: true, autoEncryption: null, or autoEncryption: 'enabled' to MongoClient options. Manually instantiating the internal Encrypter class (not supported) without an autoEncryption object.

Common situations: Treating autoEncryption as a boolean toggle instead of a config object. Typos or partial config where the autoEncryption key exists but is assigned a non-object value during refactoring.

Related errors

• Missing required option `keyVaultNamespace`
• "options" cannot contain both "keyId" and "keyAltName"
• Auth mechanism property ALLOWED_HOSTS must be an array of…
• Auto-encryption requested, but the module is not installed…
• Can only provide a custom AWS credential provider when the…

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

Appendix: source

Thrown at src/encrypter.ts:22

import { MongoInvalidArgumentError, MongoMissingDependencyError } from './error';
import { MongoClient, type MongoClientOptions } from './mongo_client';

/** @internal */
export interface EncrypterOptions {
  autoEncryption: AutoEncryptionOptions;
  maxPoolSize?: number;
}

/** @internal */
export class Encrypter {
  private internalClient: MongoClient | null;
  bypassAutoEncryption: boolean;
  needsConnecting: boolean;
  autoEncrypter: AutoEncrypter;

  constructor(client: MongoClient, uri: string, options: MongoClientOptions) {
    if (typeof options.autoEncryption !== 'object') {
      throw new MongoInvalidArgumentError('Option "autoEncryption" must be specified');
    }
    // initialize to null, if we call getInternalClient, we may set this it is important to not overwrite those function calls.
    this.internalClient = null;

    this.bypassAutoEncryption = !!options.autoEncryption.bypassAutoEncryption;
    this.needsConnecting = false;

    if (options.maxPoolSize === 0 && options.autoEncryption.keyVaultClient == null) {
      options.autoEncryption.keyVaultClient = client;
    } else if (options.autoEncryption.keyVaultClient == null) {
      options.autoEncryption.keyVaultClient = this.getInternalClient(client, uri, options);
    }

    if (this.bypassAutoEncryption) {
      options.autoEncryption.metadataClient = undefined;
    } else if (options.maxPoolSize === 0) {
      options.autoEncryption.metadataClient = client;
    } else {

View on GitHub (pinned to dce7939f86)