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

Client-Side Field Level Encryption (CSFLE) requires the native mongodb-client-encryption package which wraps libmongocrypt. When autoEncryption is enabled but the package cannot be loaded, the driver throws MongoMissingDependencyError at client construction. The native binary must match the runtime platform.

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 3366c21a63)

Solutions

Run npm install mongodb-client-encryption and add it to package.json dependencies
Rebuild native modules after Node version changes (npm rebuild)
Ensure the deployment image provides a compatible libmongocrypt runtime
If CSFLE was unintended, remove the autoEncryption option entirely

Example fix

// before
// package.json has no mongodb-client-encryption
new MongoClient(uri, { autoEncryption: { /* ... */ } });
// after
// npm install mongodb-client-encryption
new MongoClient(uri, { autoEncryption: { /* ... */ } });

Defensive patterns

Strategy: validation

Validate before calling

function assertEncryptionModule() {
  try {
    require('mongodb-client-encryption');
  } catch {
    throw new Error('Run: npm install mongodb-client-encryption');
  }
}

Try / catch

try {
  client = await MongoClient.connect(uri, { autoEncryption });
} catch (err) {
  if (err?.dependencyName === 'mongodb-client-encryption') {
    // fail fast with an actionable deploy message
    throw new Error('Missing native dep; run npm install mongodb-client-encryption');
  }
  throw err;
}

Prevention

Add mongodb-client-encryption to package.json dependencies
Smoke-test module load at container boot
Pin Node version to match the native module prebuilds
Run npm rebuild after Node upgrades

When it happens

Trigger: Enabling autoEncryption on MongoClient without installing mongodb-client-encryption; production deploy missing the optional dependency; native binary/Node ABI mismatch.

Common situations: Forgetting to add the dependency; CI cache miss; ARM/glibc/musl binary mismatch; upgrading Node without rebuilding native modules.

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/ac4ab11bac23cae3.json. Report an issue: GitHub.