{"record":{"id":"852f075d08324cc5","repo":"mongodb/node-mongodb-native","slug":"unable-to-connect-to-mongocryptd-please-make-su","errorCode":null,"errorMessage":"Unable to connect to `mongocryptd`, please make sure it is running or in your PATH for auto-spawn","messagePattern":"Unable to connect to `mongocryptd`, please make sure it is running or in your PATH for auto-spawn","errorType":"exception","errorClass":"MongoRuntimeError","httpStatus":null,"severity":"critical","filePath":"src/client-side-encryption/auto_encrypter.ts","lineNumber":390,"sourceCode":"      throw new MongoRuntimeError(\n        'Reached impossible state: mongocryptdManager is undefined when neither bypassSpawn nor the shared lib are specified.'\n      );\n    }\n    if (!this._mongocryptdClient) {\n      throw new MongoRuntimeError(\n        'Reached impossible state: mongocryptdClient is undefined when neither bypassSpawn nor the shared lib are specified.'\n      );\n    }\n\n    if (!this._mongocryptdManager.bypassSpawn) {\n      await this._mongocryptdManager.spawn();\n    }\n\n    try {\n      const client = await this._mongocryptdClient.connect();\n      return client;\n    } catch (error) {\n      throw new MongoRuntimeError(\n        'Unable to connect to `mongocryptd`, please make sure it is running or in your PATH for auto-spawn',\n        { cause: error }\n      );\n    }\n  }\n\n  /**\n   * Cleans up the `_mongocryptdClient`, if present.\n   */\n  async close(): Promise<void> {\n    await this._mongocryptdClient?.close();\n  }\n\n  /**\n   * Encrypt a command for a given namespace.\n   */\n  async encrypt(\n    ns: string,","sourceCodeStart":372,"sourceCodeEnd":408,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/client-side-encryption/auto_encrypter.ts#L372-L408","documentation":"Thrown by AutoEncrypter.init() when the driver fails to connect to mongocryptd. Mongocryptd is a companion process that analyzes commands for fields needing encryption. The driver either tried to auto-spawn it and failed, or it was expected to be running but was unreachable. This is a MongoRuntimeError with the original connection error as cause.","triggerScenarios":"Creating a MongoClient with autoEncryption without the crypt_shared library, and mongocryptd is neither running nor available for auto-spawn. The driver tries to connect to mongocryptd (default: localhost:27020 or a domain socket) and fails after serverSelectionTimeoutMS (10 seconds).","commonSituations":"Container or CI environments where mongocryptd is not installed or not in PATH; production deployments where mongocryptd was expected to be running as a service but crashed; firewall or networking issues blocking localhost connections; Docker containers where mongocryptd runs in a different container.","solutions":["Install mongocryptd and ensure it is in the system PATH for auto-spawn","Start mongocryptd manually before connecting: mongocryptd --logpath /tmp/mongocryptd.log","Install and use the crypt_shared library instead of mongocryptd (set cryptSharedLibPath or ensure it is on the system path)","If using Docker, include mongocryptd in the container image or run it as a sidecar"],"exampleFix":"// before: no mongocryptd and no crypt_shared library\nnew MongoClient(uri, {\n  autoEncryption: { kmsProviders: { ... } }\n});\nawait client.connect(); // throws during init\n\n// after: use crypt_shared library to avoid mongocryptd dependency\nnew MongoClient(uri, {\n  autoEncryption: {\n    extraOptions: { cryptSharedLibPath: '/usr/lib/mongo_crypt_v1.so' },\n    kmsProviders: { ... }\n  }\n});","handlingStrategy":"retry","validationCode":"// Check mongocryptd availability before connecting\nconst { MongoClient } = require('mongodb');\n// Verify mongocryptd is running or in PATH\nconst { execSync } = require('child_process');\ntry {\n  execSync('which mongocryptd', { stdio: 'ignore' });\n} catch {\n  console.warn('mongocryptd not found in PATH; install it or use crypt_shared library');\n}","typeGuard":null,"tryCatchPattern":"try {\n  const client = new MongoClient(uri, { autoEncryption: config });\n  await client.connect();\n} catch (error) {\n  if (error instanceof MongoRuntimeError && error.message.includes('mongocryptd')) {\n    // Start mongocryptd or install crypt_shared library, then retry\n  }\n}","preventionTips":["Install mongocryptd in the deployment environment or use the crypt_shared library","Include mongocryptd in Docker images for CSFLE-enabled applications","Consider using cryptSharedLibPath to avoid the mongocryptd process dependency entirely"],"tags":["csfle","mongocryptd","network","deployment"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}