{"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":"validation","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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/client-side-encryption/client_encryption.ts#L132-L168","documentation":"Thrown by ClientEncryption constructor (MongoCryptInvalidArgumentError) when the required options.keyVaultNamespace is null or undefined. The key vault is the collection where data encryption keys are stored, so without it the ClientEncryption cannot read or write keys and cannot function.","triggerScenarios":"Constructing `new ClientEncryption(client, { kmsProviders })` while omitting keyVaultNamespace; passing keyVaultNamespace: undefined due to a destructuring/config typo.","commonSituations":"Forgetting the option when porting from AutoEncrypter (which defaults to 'admin.datakeys'); typo in the config key; reading config from env where the variable is unset.","solutions":["Pass a 'db.collection' string for keyVaultNamespace, e.g. 'encryption.__keyVault'.","Double-check destructuring/spelling of keyVaultNamespace (note the capitalization).","If using env-driven config, default the variable at read time and fail fast with a clear message."],"exampleFix":"// before\nnew ClientEncryption(client, {\n  kmsProviders: { local: { key: localKey } }\n  // keyVaultNamespace missing\n});\n\n// after\nnew ClientEncryption(client, {\n  keyVaultNamespace: 'encryption.__keyVault',\n  kmsProviders: { local: { key: localKey } }\n});","handlingStrategy":"validation","validationCode":"function requireKeyVaultNamespace(opt) {\n  if (opt.keyVaultNamespace == null || typeof opt.keyVaultNamespace !== 'string')\n    throw new Error('keyVaultNamespace is required as a db.collection string');\n}","typeGuard":"function hasKeyVaultNamespace(opt: any): opt is { keyVaultNamespace: string } {\n  return typeof opt?.keyVaultNamespace === 'string' && opt.keyVaultNamespace.length > 0;\n}","tryCatchPattern":"try { new ClientEncryption(client, opt); }\ncatch (err) {\n  if (err instanceof MongoCryptInvalidArgumentError && /keyVaultNamespace/.test(err.message)) {\n    /* add keyVaultNamespace: 'encryption.__keyVault' */\n  } else throw err;\n}","preventionTips":["Treat keyVaultNamespace as a required field in your CSFLE config type.","Use a config loader that throws early on missing required fields.","Document the conventional value 'encryption.__keyVault' for new projects."],"tags":["csfle","configuration","client-encryption","validation"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}