{"id":"3833a8b058026d6a","repo":"mongodb/node-mongodb-native","slug":"option-keyaltnames-must-be-an-array-of-strings","errorCode":null,"errorMessage":"Option \"keyAltNames\" must be an array of strings, but was of type ${typeof options.keyAltNames}.","messagePattern":"Option \"keyAltNames\" must be an array of strings, but was of type (.+?)\\.","errorType":"validation","errorClass":"MongoCryptInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/client-side-encryption/client_encryption.ts","lineNumber":202,"sourceCode":"   *\n   * @example\n   * ```ts\n   * // Using async/await to create an aws key with a keyAltName\n   * const dataKeyId = await clientEncryption.createDataKey('aws', {\n   *   masterKey: {\n   *     region: 'us-east-1',\n   *     key: 'xxxxxxxxxxxxxx' // CMK ARN here\n   *   },\n   *   keyAltNames: [ 'mySpecialKey' ]\n   * });\n   * ```\n   */\n  async createDataKey(\n    provider: ClientEncryptionDataKeyProvider,\n    options: ClientEncryptionCreateDataKeyProviderOptions = {}\n  ): Promise<UUID> {\n    if (options.keyAltNames && !Array.isArray(options.keyAltNames)) {\n      throw new MongoCryptInvalidArgumentError(\n        `Option \"keyAltNames\" must be an array of strings, but was of type ${typeof options.keyAltNames}.`\n      );\n    }\n\n    let keyAltNames = undefined;\n    if (options.keyAltNames && options.keyAltNames.length > 0) {\n      keyAltNames = options.keyAltNames.map((keyAltName, i) => {\n        if (typeof keyAltName !== 'string') {\n          throw new MongoCryptInvalidArgumentError(\n            `Option \"keyAltNames\" must be an array of strings, but item at index ${i} was of type ${typeof keyAltName}`\n          );\n        }\n\n        return serialize({ keyAltName });\n      });\n    }\n\n    let keyMaterial = undefined;","sourceCodeStart":184,"sourceCodeEnd":220,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/client-side-encryption/client_encryption.ts#L184-L220","documentation":"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.","triggerScenarios":"Calling createDataKey('local', { keyAltNames: 'myKey' }) (a string instead of ['myKey']); passing a single value where an array is expected.","commonSituations":"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.","solutions":["Wrap the value(s) in an array: keyAltNames: ['myKey'].","If the value is dynamically typed, coerce with Array.isArray check before calling createDataKey.","Omit keyAltNames entirely if you do not need alternate key names."],"exampleFix":"// before\nawait ce.createDataKey('local', { keyAltNames: 'myKey' });\n\n// after\nawait ce.createDataKey('local', { keyAltNames: ['myKey'] });","handlingStrategy":"validation","validationCode":"function normalizeKeyAltNames(opt) {\n  if (opt.keyAltNames != null && !Array.isArray(opt.keyAltNames))\n    opt.keyAltNames = [opt.keyAltNames];\n  return opt;\n}","typeGuard":"function isStringArray(v: unknown): v is string[] {\n  return Array.isArray(v) && v.every(x => typeof x === 'string');\n}","tryCatchPattern":"try { await ce.createDataKey('local', opt); }\ncatch (err) {\n  if (err instanceof MongoCryptInvalidArgumentError && /keyAltNames\" must be an array/.test(err.message)) {\n    /* wrap in array and retry */\n  } else throw err;\n}","preventionTips":["Always pass keyAltNames as an array literal even for a single alias.","Normalize user input before constructing CSFLE options.","Add a TS type { keyAltNames?: string[] } to surface mistakes at compile time."],"tags":["csfle","client-encryption","validation","data-keys","typescript"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}