{"record":{"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":"exception","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/dce7939f86fb283e167ad709955abedb7bf23124/src/client-side-encryption/client_encryption.ts#L184-L220","documentation":"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.","triggerScenarios":"Calling createDataKey('local', { keyAltNames: 'myKey' }) with a string instead of ['myKey'], or passing an object or number as keyAltNames.","commonSituations":"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.","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"],"exampleFix":"// before\nawait clientEncryption.createDataKey('local', {\n  keyAltNames: 'myKey' // string, not array\n});\n\n// after\nawait clientEncryption.createDataKey('local', {\n  keyAltNames: ['myKey'] // array of strings\n});","handlingStrategy":"validation","validationCode":"// Before calling createDataKey\nif (options.keyAltNames != null && !Array.isArray(options.keyAltNames)) {\n  options.keyAltNames = [options.keyAltNames]; // normalize single string to array\n}\nawait clientEncryption.createDataKey('local', options);","typeGuard":"function isStringArray(value: unknown): value is string[] {\n  return Array.isArray(value) && value.every(item => typeof item === 'string');\n}","tryCatchPattern":null,"preventionTips":["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"],"tags":["csfle","validation","client-encryption","data-key"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}