mongodb/node-mongodb-native · error · MongoCryptInvalidArgumentError

Option "keyAltNames" must be an array of strings, but was…

Error message

Option "keyAltNames" must be an array of strings, but was of type ${typeof options.keyAltNames}.

What it means

Thrown by ClientEncryption.createDataKey() when the keyAltNames option is provided but is not an array. The keyAltNames parameter must be an array of strings (or undefined). Passing a single string, an object, or any other non-array type triggers this error. This is a MongoCryptInvalidArgumentError.

Solutions

Always pass keyAltNames as an array of strings, even for a single name
If keyAltNames comes from user input, normalize it to an array before passing

Example fix

// before
await clientEncryption.createDataKey('local', {
  keyAltNames: 'myKey' // string, not array
});

// after
await clientEncryption.createDataKey('local', {
  keyAltNames: ['myKey'] // array of strings
});

Defensive patterns

Strategy: validation

Validate before calling

// Before calling createDataKey
if (options.keyAltNames != null && !Array.isArray(options.keyAltNames)) {
  options.keyAltNames = [options.keyAltNames]; // normalize single string to array
}
await clientEncryption.createDataKey('local', options);

Type guard

function isStringArray(value: unknown): value is string[] {
  return Array.isArray(value) && value.every(item => typeof item === 'string');
}

Prevention

Always pass keyAltNames as an array, even for a single alt name
Normalize user input to an array before passing to createDataKey
Use TypeScript to catch non-array values at compile time

When it happens

Trigger: Calling createDataKey('local', { keyAltNames: 'myKey' }) with a string instead of ['myKey'], or passing an object or number as keyAltNames.

Common situations: Passing a single alt name as a string rather than wrapping it in an array; data from user input or config that hasn't been normalized to an array; misunderstanding the API shape from documentation examples.

Related errors

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

Appendix: source

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

   *
   * @example
   * ```ts
   * // Using async/await to create an aws key with a keyAltName
   * const dataKeyId = await clientEncryption.createDataKey('aws', {
   *   masterKey: {
   *     region: 'us-east-1',
   *     key: 'xxxxxxxxxxxxxx' // CMK ARN here
   *   },
   *   keyAltNames: [ 'mySpecialKey' ]
   * });
   * ```
   */
  async createDataKey(
    provider: ClientEncryptionDataKeyProvider,
    options: ClientEncryptionCreateDataKeyProviderOptions = {}
  ): Promise<UUID> {
    if (options.keyAltNames && !Array.isArray(options.keyAltNames)) {
      throw new MongoCryptInvalidArgumentError(
        `Option "keyAltNames" must be an array of strings, but was of type ${typeof options.keyAltNames}.`
      );
    }

    let keyAltNames = undefined;
    if (options.keyAltNames && options.keyAltNames.length > 0) {
      keyAltNames = options.keyAltNames.map((keyAltName, i) => {
        if (typeof keyAltName !== 'string') {
          throw new MongoCryptInvalidArgumentError(
            `Option "keyAltNames" must be an array of strings, but item at index ${i} was of type ${typeof keyAltName}`
          );
        }

        return serialize({ keyAltName });
      });
    }

    let keyMaterial = undefined;

View on GitHub (pinned to dce7939f86)