{"record":{"id":"d7f7273013f0470b","repo":"mongodb/node-mongodb-native","slug":"options-keyaltname-must-be-of-type-string-but-w","errorCode":null,"errorMessage":"\"options.keyAltName\" must be of type string, but was of type ${typeof keyAltName}","messagePattern":"\"options\\.keyAltName\" must be of type string, but was of type (.+?)","errorType":"exception","errorClass":"MongoCryptInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/client-side-encryption/client_encryption.ts","lineNumber":785,"sourceCode":"      rangeOptions,\n      stringOptions,\n      textOptions\n    } = options;\n    const contextOptions: ExplicitEncryptionContextOptions = {\n      expressionMode,\n      algorithm\n    };\n    if (keyId) {\n      contextOptions.keyId = keyId.buffer;\n    }\n    if (keyAltName) {\n      if (keyId) {\n        throw new MongoCryptInvalidArgumentError(\n          `\"options\" cannot contain both \"keyId\" and \"keyAltName\"`\n        );\n      }\n      if (typeof keyAltName !== 'string') {\n        throw new MongoCryptInvalidArgumentError(\n          `\"options.keyAltName\" must be of type string, but was of type ${typeof keyAltName}`\n        );\n      }\n\n      contextOptions.keyAltName = serialize({ keyAltName });\n    }\n    if (typeof contentionFactor === 'number' || typeof contentionFactor === 'bigint') {\n      contextOptions.contentionFactor = contentionFactor;\n    }\n    if (typeof queryType === 'string') {\n      contextOptions.queryType = queryType;\n    }\n\n    if (typeof rangeOptions === 'object') {\n      contextOptions.rangeOptions = serialize(rangeOptions);\n    }\n\n    const resolvedStringOptions = stringOptions ?? textOptions;","sourceCodeStart":767,"sourceCodeEnd":803,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/client-side-encryption/client_encryption.ts#L767-L803","documentation":"Thrown during CSFLE explicit encryption when options.keyAltName is present but is not a string (e.g. a number, object, or Binary). libmongocrypt serializes keyAltName as a BSON string, so only a JS string is accepted. It is a MongoCryptInvalidArgumentError raised inside _encrypt before the encryption context is created.","triggerScenarios":"Passing keyAltName as a non-string such as clientEncryption.encrypt(value, { keyAltName: 123, algorithm }) or keyAltName: someBinary; or reading keyAltName from a loosely-typed config/JSON source without coercing.","commonSituations":"Storing key alt names as numeric IDs in a config file and forwarding them unmodified; passing the whole data key document (_id Binary) into keyAltName instead of its string alt name; TypeScript any-typed option builders that bypass compile-time checks.","solutions":["Ensure options.keyAltName is a JavaScript string (the alternate name the data key was created with).","If the value comes from dynamic input, coerce/validate: if (typeof keyAltName !== 'string') throw ... before calling encrypt.","Use createDataKey with keyAltNames: ['myName'] first, then pass that exact string to encrypt."],"exampleFix":"// before\nawait clientEncryption.encrypt(value, {\n  algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-DETERMINISTIC',\n  keyAltName: keyDocument._id // Binary, not a string\n});\n// after\nawait clientEncryption.encrypt(value, {\n  algorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-DETERMINISTIC',\n  keyAltName: 'customerKey' // the string alt name\n});","handlingStrategy":"type-guard","validationCode":"if (options.keyAltName != null && typeof options.keyAltName !== 'string') {\n  throw new TypeError('options.keyAltName must be a string');\n}","typeGuard":"function isKeyAltName(v: unknown): v is string {\n  return typeof v === 'string' && v.length > 0;\n}","tryCatchPattern":null,"preventionTips":["Type encrypt options with the driver's ClientEncryptionEncryptOptions so the compiler rejects non-string keyAltName.","Do not store key alt names as numbers/objects in config."],"tags":["csfle","client-side-encryption","validation","typescript"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}