{"id":"98abd03b7512b68f","repo":"mongodb/node-mongodb-native","slug":"cryptsharedlibrequired-set-but-no-crypt-shared-l","errorCode":null,"errorMessage":"`cryptSharedLibRequired` set but no crypt_shared library loaded","messagePattern":"`cryptSharedLibRequired` set but no crypt_shared library loaded","errorType":"validation","errorClass":"MongoCryptInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/client-side-encryption/auto_encrypter.ts","lineNumber":328,"sourceCode":"    this._bypassMongocryptdAndCryptShared = this._bypassEncryption || !!options.bypassQueryAnalysis;\n\n    if (options.extraOptions && options.extraOptions.cryptSharedLibSearchPaths) {\n      // Only for driver testing\n      mongoCryptOptions.cryptSharedLibSearchPaths = options.extraOptions.cryptSharedLibSearchPaths;\n    } else if (!this._bypassMongocryptdAndCryptShared) {\n      mongoCryptOptions.cryptSharedLibSearchPaths = ['$SYSTEM'];\n    }\n\n    const MongoCrypt = AutoEncrypter.getMongoCrypt();\n    this._mongocrypt = new MongoCrypt(mongoCryptOptions);\n    this._contextCounter = 0;\n\n    if (\n      options.extraOptions &&\n      options.extraOptions.cryptSharedLibRequired &&\n      !this.cryptSharedLibVersionInfo\n    ) {\n      throw new MongoCryptInvalidArgumentError(\n        '`cryptSharedLibRequired` set but no crypt_shared library loaded'\n      );\n    }\n\n    // Only instantiate mongocryptd manager/client once we know for sure\n    // that we are not using the CSFLE shared library.\n    if (!this._bypassMongocryptdAndCryptShared && !this.cryptSharedLibVersionInfo) {\n      this._mongocryptdManager = new MongocryptdManager(options.extraOptions);\n      const clientOptions: MongoClientOptions = {\n        serverSelectionTimeoutMS: 10000\n      };\n\n      if (\n        (options.extraOptions == null || typeof options.extraOptions.mongocryptdURI !== 'string') &&\n        !net.getDefaultAutoSelectFamily\n      ) {\n        // Only set family if autoSelectFamily options are not supported.\n        clientOptions.family = 4;","sourceCodeStart":310,"sourceCodeEnd":346,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/client-side-encryption/auto_encrypter.ts#L310-L346","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Point extraOptions.cryptSharedLibPath at the absolute path of the loaded library.","If mongocryptd is acceptable, remove cryptSharedLibRequired (or set it false) so the driver falls back to spawning mongocryptd."],"exampleFix":"// before\nautoEncryption: {\n  extraOptions: { cryptSharedLibRequired: true }\n  // libmongocrypt.so not installed\n}\n\n// after\nautoEncryption: {\n  extraOptions: { cryptSharedLibPath: '/usr/lib/libmongocrypt.so', cryptSharedLibRequired: true }\n}","handlingStrategy":"validation","validationCode":"function ensureCryptShared(opt, loadedVersion) {\n  if (opt.extraOptions?.cryptSharedLibRequired && !loadedVersion)\n    throw new Error('crypt_shared required but not loaded');\n}","typeGuard":"// Not applicable: depends on runtime presence of a native library.","tryCatchPattern":"try { new MongoClient(uri, { autoEncryption: opt }); }\ncatch (err) {\n  if (err instanceof MongoCryptInvalidArgumentError && /cryptSharedLibRequired/.test(err.message)) {\n    /* install crypt_shared or drop the flag */\n  } else throw err;\n}","preventionTips":["Install the mongodb-crypt package and set LD_LIBRARY_PATH in the runtime environment.","Pin cryptSharedLibPath to an absolute path for reproducibility.","Smoke-test CSFLE client construction in CI on every runner image."],"tags":["csfle","configuration","crypt-shared","deployment","native-library"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}