mongodb/node-mongodb-native · error · MongoCryptInvalidArgumentError

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

Error message

Option "keyAltNames" must be an array of strings, but item at index ${i} was of type ${typeof keyAltName}

What it means

Thrown by ClientEncryption.createDataKey() when the keyAltNames option is an array but one or more of its elements is not a string. Each alternate name must be a string because it is serialized as a BSON string key for lookups. The error message includes the index and type of the offending element. This is a MongoCryptInvalidArgumentError.

Solutions

Filter or map keyAltNames to ensure every element is a string before passing it
Validate each element with typeof === 'string' before calling createDataKey

Example fix

// before
await clientEncryption.createDataKey('local', {
  keyAltNames: ['myKey', 42, null]
});

// after
const rawNames = ['myKey', 42, null];
const keyAltNames = rawNames.filter(n => typeof n === 'string');
await clientEncryption.createDataKey('local', { keyAltNames });

Defensive patterns

Strategy: validation

Validate before calling

// Before calling createDataKey
if (options.keyAltNames) {
  const valid = options.keyAltNames.every((name: unknown) => typeof name === 'string');
  if (!valid) {
    options.keyAltNames = options.keyAltNames.filter((name: unknown) => typeof name === 'string');
  }
}
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

Filter keyAltNames arrays to remove non-string elements before calling createDataKey
Validate user-provided alt names with a typeof check
Use TypeScript strict type checking to prevent non-string values in the array

When it happens

Trigger: Calling createDataKey with keyAltNames: ['valid', 123, 'alsoValid'] or keyAltNames: [null] or keyAltNames: [{ name: 'x' }]. Any non-string element at any index triggers this.

Common situations: Processing unvalidated user input that contains mixed-type arrays; numeric IDs being included in keyAltNames; null or undefined values in the array from optional chaining or partial data.

Related errors

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

Appendix: source

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

   *   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;
    if (options.keyMaterial) {
      keyMaterial = serialize({ keyMaterial: options.keyMaterial });
    }

    const dataKeyBson = serialize({
      provider,
      ...options.masterKey
    });

View on GitHub (pinned to dce7939f86)