mongodb/node-mongodb-native · critical · MongoMissingDependencyError

Auto-encryption requested, but the module is not installed…

Error message

Auto-encryption requested, but the module is not installed. Please add `mongodb-client-encryption` as a dependency of your project

What it means

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.

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.

Example fix

# before: autoEncryption used but package not installed
# after
npm install mongodb-client-encryption

Defensive patterns

Strategy: validation

Validate before calling

function hasClientEncryption() {
  try {
    require.resolve('mongodb-client-encryption');
    return true;
  } catch {
    return false;
  }
}
if (opts.autoEncryption && !hasClientEncryption()) {
  throw new Error('Install mongodb-client-encryption before enabling autoEncryption');
}

Type guard

declare function hasMongoCrypt(): boolean;
// runtime check via require.resolve as shown in validationCode

Try / catch

try {
  const client = new MongoClient(uri, { autoEncryption: {...} });
  await client.connect();
} catch (e) {
  if (e instanceof MongoMissingDependencyError && /mongodb-client-encryption/.test(e.message)) {
    // prompt install, fall back to non-encrypted client
  }
  throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/ac4ab11bac23cae3. Report an issue: GitHub.

Appendix: source

Thrown at src/encrypter.ts:117

    let error;
    try {
      await this.autoEncrypter.close();
    } catch (autoEncrypterError) {
      error = autoEncrypterError;
    }
    const internalClient = this.internalClient;
    if (internalClient != null && client !== internalClient) {
      return await internalClient.close();
    }
    if (error != null) {
      throw error;
    }
  }

  static checkForMongoCrypt(): void {
    const mongodbClientEncryption = getMongoDBClientEncryption();
    if ('kModuleError' in mongodbClientEncryption) {
      throw new MongoMissingDependencyError(
        'Auto-encryption requested, but the module is not installed. ' +
          'Please add `mongodb-client-encryption` as a dependency of your project',
        {
          cause: mongodbClientEncryption['kModuleError'],
          dependencyName: 'mongodb-client-encryption'
        }
      );
    }
  }
}

View on GitHub (pinned to dce7939f86)