What causes "Missing required option `keyVaultNamespace`" in mongodb/node-mongodb-native?

Provide keyVaultNamespace as a string in 'database.collection' format, e.g., 'encryption.__keyVault'

mongodb/node-mongodb-native · error · MongoCryptInvalidArgumentError

Missing required option `keyVaultNamespace`

Error message

Missing required option `keyVaultNamespace`

What it means

Thrown by the ClientEncryption constructor when the keyVaultNamespace option is not provided (null or undefined). The key vault namespace specifies where data encryption keys are stored (e.g., 'encryption.__keyVault') and is mandatory for all ClientEncryption operations. This is a MongoCryptInvalidArgumentError.

Solutions

Provide keyVaultNamespace as a string in 'database.collection' format, e.g., 'encryption.__keyVault'
Ensure the database and collection names are valid MongoDB namespace components
If loading config from a file, verify the keyVaultNamespace key is present and correctly spelled

Example fix

// before
new ClientEncryption(client, {
  kmsProviders: { local: { key: masterKey } }
}); // missing keyVaultNamespace

// after
new ClientEncryption(client, {
  keyVaultNamespace: 'encryption.__keyVault',
  kmsProviders: { local: { key: masterKey } }
});

Defensive patterns

Strategy: validation

Validate before calling

// Before creating ClientEncryption
if (!options?.keyVaultNamespace) {
  throw new TypeError('keyVaultNamespace is required, e.g., "encryption.__keyVault"');
}
const encryption = new ClientEncryption(client, options);

Type guard

function hasKeyVaultNamespace(options: unknown): options is { keyVaultNamespace: string } {
  return typeof (options as any)?.keyVaultNamespace === 'string' && (options as any).keyVaultNamespace.length > 0;
}

Prevention

Always include keyVaultNamespace in ClientEncryption options
Use TypeScript to enforce the option at compile time (it is required in the type)
Validate config loaded from external files for required keys before use

When it happens

Trigger: Creating new ClientEncryption(client, { kmsProviders: {...} }) without specifying keyVaultNamespace. The constructor checks for its presence before proceeding.

Common situations: Forgetting the keyVaultNamespace option when setting up explicit encryption; copying a partial configuration that omits this field; type-loose configuration objects (e.g., from JSON config files) where the key is misspelled or absent.

Related errors

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

Appendix: source

Thrown at src/client-side-encryption/client_encryption.ts:150

      throw new MongoCryptInvalidArgumentError(
        'Cannot set both proxyOptions and kmsConnectCallback'
      );
    }
    this._tlsOptions = options.tlsOptions ?? {};
    this._kmsConnectCallback = options.kmsConnectCallback;
    this._kmsProviders = options.kmsProviders || {};
    const { timeoutMS } = resolveTimeoutOptions(client, options);
    this._timeoutMS = timeoutMS;
    this._credentialProviders = options.credentialProviders;

    if (options.credentialProviders?.aws && !isEmptyCredentials('aws', this._kmsProviders)) {
      throw new MongoCryptInvalidArgumentError(
        'Can only provide a custom AWS credential provider when the state machine is configured for automatic AWS credential fetching'
      );
    }

    if (options.keyVaultNamespace == null) {
      throw new MongoCryptInvalidArgumentError('Missing required option `keyVaultNamespace`');
    }

    const mongoCryptOptions: MongoCryptOptions = {
      ...options,
      kmsProviders: serialize(this._kmsProviders),
      errorWrapper: defaultErrorWrapper
    };

    this._keyVaultNamespace = options.keyVaultNamespace;
    this._keyVaultClient = options.keyVaultClient || client;
    const MongoCrypt = ClientEncryption.getMongoCrypt();
    this._mongoCrypt = new MongoCrypt(mongoCryptOptions);
  }

  /**
   * Creates a data key used for explicit encryption and inserts it into the key vault namespace
   *
   * @example

View on GitHub (pinned to dce7939f86)