mongodb/node-mongodb-native · error · MongoCryptInvalidArgumentError

`cryptSharedLibRequired` set but no crypt_shared library…

Error message

`cryptSharedLibRequired` set but no crypt_shared library loaded

What it means

Thrown by the AutoEncrypter constructor when extraOptions.cryptSharedLibRequired is true but the driver could not load the MongoDB Crypt shared library (cryptSharedLibVersionInfo is null). The crypt_shared library is an alternative to mongocryptd for query analysis. Marking it required tells the driver to fail rather than fall back to mongocryptd. This is a MongoCryptInvalidArgumentError.

Solutions

  1. Install the MongoDB Crypt shared library on the system (available with MongoDB 6.0+ server packages)
  2. Ensure the library is on the system's shared library search path (LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on macOS, PATH on Windows)
  3. Alternatively, set cryptSharedLibPath to the full path of the library file
  4. If mongocryptd is acceptable as a fallback, remove cryptSharedLibRequired or set it to false

Example fix

// before
new MongoClient(uri, {
  autoEncryption: {
    extraOptions: { cryptSharedLibRequired: true },
    kmsProviders: { ... }
  }
}); // throws if library not found

// after (explicit path)
new MongoClient(uri, {
  autoEncryption: {
    extraOptions: {
      cryptSharedLibPath: '/opt/mongo_crypt_v1.so',
      cryptSharedLibRequired: true
    },
    kmsProviders: { ... }
  }
});
Defensive patterns

Strategy: validation

Validate before calling

// Before constructing MongoClient, verify crypt_shared library availability
import { AutoEncrypter } from 'mongodb';
// After construction, check:
if (autoEncryptionConfig.extraOptions?.cryptSharedLibRequired) {
  // Ensure library is installed and on the system path before proceeding
  console.warn('crypt_shared library required; verify it is installed');
}

Try / catch

try {
  const client = new MongoClient(uri, { autoEncryption: config });
  await client.connect();
} catch (error) {
  if (error instanceof MongoCryptInvalidArgumentError && error.message.includes('cryptSharedLibRequired')) {
    // Install crypt_shared library or switch to mongocryptd fallback
  }
}

Prevention

When it happens

Trigger: Setting extraOptions: { cryptSharedLibRequired: true } in autoEncryption config on a system where the crypt_shared library (mongo_crypt_v1.so / .dylib / .dll) is not installed or not on the system library search path.

Common situations: Deploying to a new server or container without the crypt_shared library installed; requiring crypt_shared for consistency but the deployment image lacks it; upgrading MongoDB server versions and the crypt_shared library path changed.

Related errors

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

Appendix: source

Thrown at src/client-side-encryption/auto_encrypter.ts:328

    this._bypassMongocryptdAndCryptShared = this._bypassEncryption || !!options.bypassQueryAnalysis;

    if (options.extraOptions && options.extraOptions.cryptSharedLibSearchPaths) {
      // Only for driver testing
      mongoCryptOptions.cryptSharedLibSearchPaths = options.extraOptions.cryptSharedLibSearchPaths;
    } else if (!this._bypassMongocryptdAndCryptShared) {
      mongoCryptOptions.cryptSharedLibSearchPaths = ['$SYSTEM'];
    }

    const MongoCrypt = AutoEncrypter.getMongoCrypt();
    this._mongocrypt = new MongoCrypt(mongoCryptOptions);
    this._contextCounter = 0;

    if (
      options.extraOptions &&
      options.extraOptions.cryptSharedLibRequired &&
      !this.cryptSharedLibVersionInfo
    ) {
      throw new MongoCryptInvalidArgumentError(
        '`cryptSharedLibRequired` set but no crypt_shared library loaded'
      );
    }

    // Only instantiate mongocryptd manager/client once we know for sure
    // that we are not using the CSFLE shared library.
    if (!this._bypassMongocryptdAndCryptShared && !this.cryptSharedLibVersionInfo) {
      this._mongocryptdManager = new MongocryptdManager(options.extraOptions);
      const clientOptions: MongoClientOptions = {
        serverSelectionTimeoutMS: 10000
      };

      if (
        (options.extraOptions == null || typeof options.extraOptions.mongocryptdURI !== 'string') &&
        !net.getDefaultAutoSelectFamily
      ) {
        // Only set family if autoSelectFamily options are not supported.
        clientOptions.family = 4;

View on GitHub (pinned to dce7939f86)