mongodb/node-mongodb-native · error · MongoCryptInvalidArgumentError

`cryptSharedLibRequired` set but no crypt_shared library loa

Error message

`cryptSharedLibRequired` set but no crypt_shared library loaded

What it means

Thrown by AutoEncrypter constructor (MongoCryptInvalidArgumentError) when autoEncryption.extraOptions.cryptSharedLibRequired is true but the driver could not load MongoDB's crypt_shared library from the system search paths. The flag explicitly forbids falling back to mongocryptd, so the driver aborts startup rather than silently downgrading.

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

Solutions

1. Install the crypt_shared library (mongodb-crypt package) on the host and ensure its directory is in LD_LIBRARY_PATH (Linux)/DYLD_LIBRARY_PATH (macOS).
2. Point extraOptions.cryptSharedLibPath at the absolute path of the loaded library.
3. If mongocryptd is acceptable, remove cryptSharedLibRequired (or set it false) so the driver falls back to spawning mongocryptd.

Example fix

// before
autoEncryption: {
  extraOptions: { cryptSharedLibRequired: true }
  // libmongocrypt.so not installed
}

// after
autoEncryption: {
  extraOptions: { cryptSharedLibPath: '/usr/lib/libmongocrypt.so', cryptSharedLibRequired: true }
}

function ensureCryptShared(opt, loadedVersion) {
  if (opt.extraOptions?.cryptSharedLibRequired && !loadedVersion)
    throw new Error('crypt_shared required but not loaded');
}

// Not applicable: depends on runtime presence of a native library.

try { new MongoClient(uri, { autoEncryption: opt }); }
catch (err) {
  if (err instanceof MongoCryptInvalidArgumentError && /cryptSharedLibRequired/.test(err.message)) {
    /* install crypt_shared or drop the flag */
  } else throw err;
}

When it happens

Trigger: Setting extraOptions.cryptSharedLibRequired: true on a host where crypt_shared is not installed or not on LD_LIBRARY_PATH/DYLD_LIBRARY_PATH/PATH, or where cryptSharedLibSearchPaths does not contain the installed location.

Common situations: Deploying to a new environment without the crypt_shared package installed; container images missing libmongocrypt; CI that sets cryptSharedLibRequired but installs the shared lib only on some runners; PATH set incorrectly for the node process.

Related errors

• Unable to connect to `mongocryptd`, please make sure it is r
• Cannot set both proxyOptions and kmsConnectCallback
• Can only provide a custom AWS credential provider when the s
• Cannot set both proxyOptions and kmsConnectCallback
• Can only provide a custom AWS credential provider when the s

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