{"record":{"id":"ac4ab11bac23cae3","repo":"mongodb/node-mongodb-native","slug":"auto-encryption-requested-but-the-module-is-not-i","errorCode":null,"errorMessage":"Auto-encryption requested, but the module is not installed. Please add `mongodb-client-encryption` as a dependency of your project","messagePattern":"Auto-encryption requested, but the module is not installed\\. Please add `mongodb-client-encryption` as a dependency of your project","errorType":"exception","errorClass":"MongoMissingDependencyError","httpStatus":null,"severity":"critical","filePath":"src/encrypter.ts","lineNumber":117,"sourceCode":"    let error;\n    try {\n      await this.autoEncrypter.close();\n    } catch (autoEncrypterError) {\n      error = autoEncrypterError;\n    }\n    const internalClient = this.internalClient;\n    if (internalClient != null && client !== internalClient) {\n      return await internalClient.close();\n    }\n    if (error != null) {\n      throw error;\n    }\n  }\n\n  static checkForMongoCrypt(): void {\n    const mongodbClientEncryption = getMongoDBClientEncryption();\n    if ('kModuleError' in mongodbClientEncryption) {\n      throw new MongoMissingDependencyError(\n        'Auto-encryption requested, but the module is not installed. ' +\n          'Please add `mongodb-client-encryption` as a dependency of your project',\n        {\n          cause: mongodbClientEncryption['kModuleError'],\n          dependencyName: 'mongodb-client-encryption'\n        }\n      );\n    }\n  }\n}\n","sourceCodeStart":99,"sourceCodeEnd":128,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/encrypter.ts#L99-L128","documentation":"When autoEncryption is enabled, the driver requires the native mongodb-client-encryption package (which wraps libmongocrypt). Encrypter.checkForMongoCrypt() (src/encrypter.ts:114) resolves the optional dependency and, if it is missing, throws a MongoMissingDependencyError pointing the user to install it. This is raised during MongoClient construction/connect, before any encryption can occur.","triggerScenarios":"Creating a MongoClient with an autoEncryption option without having run npm install mongodb-client-encryption. Using a stripped/production bundle or a monorepo workspace where the optional dep was hoisted away.","commonSituations":"Fresh clone of a CSFLE-enabled project where dependencies were installed with --omit=optional or an npm config that skips optional deps. Deploying to an environment (e.g. serverless) where native addon build tools are missing, so the optional package silently failed to install.","solutions":["Install the dependency: npm install mongodb-client-encryption (ensure libmongocrypt's build prerequisites are present on the system).","If using a package manager that prunes optional deps, ensure optional dependencies are not skipped (remove --no-optional / check .npmrc 'omit').","Verify the package resolves at runtime: require('mongodb-client-encryption') in the target environment."],"exampleFix":"# before: autoEncryption used but package not installed\n# after\nnpm install mongodb-client-encryption","handlingStrategy":"validation","validationCode":"function hasClientEncryption() {\n  try {\n    require.resolve('mongodb-client-encryption');\n    return true;\n  } catch {\n    return false;\n  }\n}\nif (opts.autoEncryption && !hasClientEncryption()) {\n  throw new Error('Install mongodb-client-encryption before enabling autoEncryption');\n}","typeGuard":"declare function hasMongoCrypt(): boolean;\n// runtime check via require.resolve as shown in validationCode","tryCatchPattern":"try {\n  const client = new MongoClient(uri, { autoEncryption: {...} });\n  await client.connect();\n} catch (e) {\n  if (e instanceof MongoMissingDependencyError && /mongodb-client-encryption/.test(e.message)) {\n    // prompt install, fall back to non-encrypted client\n  }\n  throw e;\n}","preventionTips":["Install mongodb-client-encryption in the same step as enabling autoEncryption.","In CI/deploy, verify require.resolve('mongodb-client-encryption') succeeds before running.","Ensure native build tools (python, make, C++ compiler) are present so the optional dep builds."],"tags":["csfle","dependency","native-module","configuration"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}