mongodb/node-mongodb-native · error · MongoCryptInvalidArgumentError

Missing required option `keyVaultNamespace`

Error message

Missing required option `keyVaultNamespace`

What it means

Thrown by ClientEncryption constructor (MongoCryptInvalidArgumentError) when the required options.keyVaultNamespace is null or undefined. The key vault is the collection where data encryption keys are stored, so without it the ClientEncryption cannot read or write keys and cannot function.

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 3366c21a63)

Solutions

1. Pass a 'db.collection' string for keyVaultNamespace, e.g. 'encryption.__keyVault'.
2. Double-check destructuring/spelling of keyVaultNamespace (note the capitalization).
3. If using env-driven config, default the variable at read time and fail fast with a clear message.

Example fix

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

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

function requireKeyVaultNamespace(opt) {
  if (opt.keyVaultNamespace == null || typeof opt.keyVaultNamespace !== 'string')
    throw new Error('keyVaultNamespace is required as a db.collection string');
}

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

try { new ClientEncryption(client, opt); }
catch (err) {
  if (err instanceof MongoCryptInvalidArgumentError && /keyVaultNamespace/.test(err.message)) {
    /* add keyVaultNamespace: 'encryption.__keyVault' */
  } else throw err;
}

When it happens

Trigger: Constructing `new ClientEncryption(client, { kmsProviders })` while omitting keyVaultNamespace; passing keyVaultNamespace: undefined due to a destructuring/config typo.

Common situations: Forgetting the option when porting from AutoEncrypter (which defaults to 'admin.datakeys'); typo in the config key; reading config from env where the variable is unset.

Related errors

• Cannot set both proxyOptions and kmsConnectCallback
• Can only provide a custom AWS credential provider when the s
• Option "keyAltNames" must be an array of strings, but was of
• Option "keyAltNames" must be an array of strings, but item a
• "options" cannot contain both "keyId" and "keyAltName"

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/ca392d1335843a74.json. Report an issue: GitHub.