{"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":"validation","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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/client-side-encryption/client_encryption.ts#L193-L229","documentation":"Thrown by ClientEncryption.createDataKey (MongoCryptInvalidArgumentError) when options.keyAltNames is an array but one of its elements is not a string. The message names the offending index so you can locate the bad element. Each alias is serialized to BSON by key, so non-string items break serialization.","triggerScenarios":"Calling createDataKey with keyAltNames: ['valid', 42] or keyAltNames: [null, 'x']; mixing types when the array is built dynamically.","commonSituations":"Building keyAltNames from user input or a config that permits non-strings; deserialized JSON containing numbers; refactoring that leaves a placeholder null.","solutions":["Sanitize the array so every element is a string: keyAltNames.filter(x => typeof x === 'string').","Fix the source of the offending element so only strings reach the option.","Add a unit test that asserts all elements are strings before createDataKey is called."],"exampleFix":"// before\nawait ce.createDataKey('local', { keyAltNames: ['myKey', 123] });\n\n// after\nawait ce.createDataKey('local', { keyAltNames: ['myKey', '123'] });","handlingStrategy":"validation","validationCode":"function sanitizeKeyAltNames(opt) {\n  if (Array.isArray(opt.keyAltNames))\n    opt.keyAltNames = opt.keyAltNames.filter(x => typeof x === 'string');\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 && /item at index/.test(err.message)) {\n    /* coerce/filter non-strings out of keyAltNames */\n  } else throw err;\n}","preventionTips":["Filter keyAltNames to strings before calling createDataKey.","Type the option as string[] so TS catches non-strings at the source.","Test with mixed-type input to confirm sanitization."],"tags":["csfle","client-encryption","validation","data-keys","typescript"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}