mongodb/node-mongodb-native · error · MongoCryptInvalidArgumentError

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

Error message

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

What it means

Thrown by ClientEncryption.createDataKey (MongoCryptInvalidArgumentError) when the options.keyAltNames field is provided but is not an array. keyAltNames must be an array of strings so the driver can serialize each alternate name as a separate BSON document for the key vault.

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

Solutions

1. Wrap the value(s) in an array: keyAltNames: ['myKey'].
2. If the value is dynamically typed, coerce with Array.isArray check before calling createDataKey.
3. Omit keyAltNames entirely if you do not need alternate key names.

Example fix

// before
await ce.createDataKey('local', { keyAltNames: 'myKey' });

// after
await ce.createDataKey('local', { keyAltNames: ['myKey'] });

function normalizeKeyAltNames(opt) {
  if (opt.keyAltNames != null && !Array.isArray(opt.keyAltNames))
    opt.keyAltNames = [opt.keyAltNames];
  return opt;
}

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

try { await ce.createDataKey('local', opt); }
catch (err) {
  if (err instanceof MongoCryptInvalidArgumentError && /keyAltNames" must be an array/.test(err.message)) {
    /* wrap in array and retry */
  } else throw err;
}

When it happens

Trigger: Calling createDataKey('local', { keyAltNames: 'myKey' }) (a string instead of ['myKey']); passing a single value where an array is expected.

Common situations: Misreading the API and passing a scalar alias; dynamically building options where the variable is sometimes a string; copy-paste from docs that show a single-alias example without the brackets.

Related errors

• Option "keyAltNames" must be an array of strings, but item a
• "options.keyAltName" must be of type string, but was of type
• Missing required option `keyVaultNamespace`
• Unable to complete creating data keys: ${cause.message}
• "options" cannot contain both "keyId" and "keyAltName"

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