{"record":{"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":"exception","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/dce7939f86fb283e167ad709955abedb7bf23124/src/client-side-encryption/auto_encrypter.ts#L310-L346","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install the MongoDB Crypt shared library on the system (available with MongoDB 6.0+ server packages)","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)","Alternatively, set cryptSharedLibPath to the full path of the library file","If mongocryptd is acceptable as a fallback, remove cryptSharedLibRequired or set it to false"],"exampleFix":"// before\nnew MongoClient(uri, {\n  autoEncryption: {\n    extraOptions: { cryptSharedLibRequired: true },\n    kmsProviders: { ... }\n  }\n}); // throws if library not found\n\n// after (explicit path)\nnew MongoClient(uri, {\n  autoEncryption: {\n    extraOptions: {\n      cryptSharedLibPath: '/opt/mongo_crypt_v1.so',\n      cryptSharedLibRequired: true\n    },\n    kmsProviders: { ... }\n  }\n});","handlingStrategy":"validation","validationCode":"// Before constructing MongoClient, verify crypt_shared library availability\nimport { AutoEncrypter } from 'mongodb';\n// After construction, check:\nif (autoEncryptionConfig.extraOptions?.cryptSharedLibRequired) {\n  // Ensure library is installed and on the system path before proceeding\n  console.warn('crypt_shared library required; verify it is installed');\n}","typeGuard":null,"tryCatchPattern":"try {\n  const client = new MongoClient(uri, { autoEncryption: config });\n  await client.connect();\n} catch (error) {\n  if (error instanceof MongoCryptInvalidArgumentError && error.message.includes('cryptSharedLibRequired')) {\n    // Install crypt_shared library or switch to mongocryptd fallback\n  }\n}","preventionTips":["Install the MongoDB Crypt shared library in deployment environments before using cryptSharedLibRequired","Set cryptSharedLibPath explicitly to avoid path resolution issues","In CI/CD, include the crypt_shared library in the build image"],"tags":["csfle","configuration","crypt-shared-library","deployment"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}