{"record":{"id":"61d7691c046638bf","repo":"mongodb/node-mongodb-native","slug":"option-keyaltnames-must-be-an-array-of-strings-61d769","errorCode":null,"errorMessage":"Option \"keyAltNames\" must be an array of strings, but item at index ${i} was of type ${typeof keyAltName}","messagePattern":"Option \"keyAltNames\" must be an array of strings, but item at index (.+?) was of type (.+?)","errorType":"exception","errorClass":"MongoCryptInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/client-side-encryption/client_encryption.ts","lineNumber":211,"sourceCode":"   *   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;\n    if (options.keyMaterial) {\n      keyMaterial = serialize({ keyMaterial: options.keyMaterial });\n    }\n\n    const dataKeyBson = serialize({\n      provider,\n      ...options.masterKey\n    });\n","sourceCodeStart":193,"sourceCodeEnd":229,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/client-side-encryption/client_encryption.ts#L193-L229","documentation":"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.","triggerScenarios":"Calling createDataKey with keyAltNames: ['valid', 123, 'alsoValid'] or keyAltNames: [null] or keyAltNames: [{ name: 'x' }]. Any non-string element at any index triggers this.","commonSituations":"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.","solutions":["Filter or map keyAltNames to ensure every element is a string before passing it","Validate each element with typeof === 'string' before calling createDataKey"],"exampleFix":"// before\nawait clientEncryption.createDataKey('local', {\n  keyAltNames: ['myKey', 42, null]\n});\n\n// after\nconst rawNames = ['myKey', 42, null];\nconst keyAltNames = rawNames.filter(n => typeof n === 'string');\nawait clientEncryption.createDataKey('local', { keyAltNames });","handlingStrategy":"validation","validationCode":"// Before calling createDataKey\nif (options.keyAltNames) {\n  const valid = options.keyAltNames.every((name: unknown) => typeof name === 'string');\n  if (!valid) {\n    options.keyAltNames = options.keyAltNames.filter((name: unknown) => typeof name === 'string');\n  }\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":["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"],"tags":["csfle","validation","client-encryption","data-key","types"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}