{"record":{"id":"ca392d1335843a74","repo":"mongodb/node-mongodb-native","slug":"missing-required-option-keyvaultnamespace","errorCode":null,"errorMessage":"Missing required option `keyVaultNamespace`","messagePattern":"Missing required option `keyVaultNamespace`","errorType":"exception","errorClass":"MongoCryptInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/client-side-encryption/client_encryption.ts","lineNumber":150,"sourceCode":"      throw new MongoCryptInvalidArgumentError(\n        'Cannot set both proxyOptions and kmsConnectCallback'\n      );\n    }\n    this._tlsOptions = options.tlsOptions ?? {};\n    this._kmsConnectCallback = options.kmsConnectCallback;\n    this._kmsProviders = options.kmsProviders || {};\n    const { timeoutMS } = resolveTimeoutOptions(client, options);\n    this._timeoutMS = timeoutMS;\n    this._credentialProviders = options.credentialProviders;\n\n    if (options.credentialProviders?.aws && !isEmptyCredentials('aws', this._kmsProviders)) {\n      throw new MongoCryptInvalidArgumentError(\n        'Can only provide a custom AWS credential provider when the state machine is configured for automatic AWS credential fetching'\n      );\n    }\n\n    if (options.keyVaultNamespace == null) {\n      throw new MongoCryptInvalidArgumentError('Missing required option `keyVaultNamespace`');\n    }\n\n    const mongoCryptOptions: MongoCryptOptions = {\n      ...options,\n      kmsProviders: serialize(this._kmsProviders),\n      errorWrapper: defaultErrorWrapper\n    };\n\n    this._keyVaultNamespace = options.keyVaultNamespace;\n    this._keyVaultClient = options.keyVaultClient || client;\n    const MongoCrypt = ClientEncryption.getMongoCrypt();\n    this._mongoCrypt = new MongoCrypt(mongoCryptOptions);\n  }\n\n  /**\n   * Creates a data key used for explicit encryption and inserts it into the key vault namespace\n   *\n   * @example","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/client-side-encryption/client_encryption.ts#L132-L168","documentation":"Thrown by the ClientEncryption constructor when the keyVaultNamespace option is not provided (null or undefined). The key vault namespace specifies where data encryption keys are stored (e.g., 'encryption.__keyVault') and is mandatory for all ClientEncryption operations. This is a MongoCryptInvalidArgumentError.","triggerScenarios":"Creating new ClientEncryption(client, { kmsProviders: {...} }) without specifying keyVaultNamespace. The constructor checks for its presence before proceeding.","commonSituations":"Forgetting the keyVaultNamespace option when setting up explicit encryption; copying a partial configuration that omits this field; type-loose configuration objects (e.g., from JSON config files) where the key is misspelled or absent.","solutions":["Provide keyVaultNamespace as a string in 'database.collection' format, e.g., 'encryption.__keyVault'","Ensure the database and collection names are valid MongoDB namespace components","If loading config from a file, verify the keyVaultNamespace key is present and correctly spelled"],"exampleFix":"// before\nnew ClientEncryption(client, {\n  kmsProviders: { local: { key: masterKey } }\n}); // missing keyVaultNamespace\n\n// after\nnew ClientEncryption(client, {\n  keyVaultNamespace: 'encryption.__keyVault',\n  kmsProviders: { local: { key: masterKey } }\n});","handlingStrategy":"validation","validationCode":"// Before creating ClientEncryption\nif (!options?.keyVaultNamespace) {\n  throw new TypeError('keyVaultNamespace is required, e.g., \"encryption.__keyVault\"');\n}\nconst encryption = new ClientEncryption(client, options);","typeGuard":"function hasKeyVaultNamespace(options: unknown): options is { keyVaultNamespace: string } {\n  return typeof (options as any)?.keyVaultNamespace === 'string' && (options as any).keyVaultNamespace.length > 0;\n}","tryCatchPattern":null,"preventionTips":["Always include keyVaultNamespace in ClientEncryption options","Use TypeScript to enforce the option at compile time (it is required in the type)","Validate config loaded from external files for required keys before use"],"tags":["csfle","configuration","client-encryption","validation"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}