{"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":"error","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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/client-side-encryption/auto_encrypter.ts#L372-L408","documentation":"Thrown by AutoEncrypter.init() (MongoRuntimeError wrapping an underlying connection failure) when the driver cannot connect to mongocryptd, the sidecar process used for query analysis when crypt_shared is not loaded. init() first attempts to auto-spawn mongocryptd and then connect; both the spawn and the connect are wrapped so any failure surfaces as this message.","triggerScenarios":"Using CSFLE without crypt_shared installed, with mongocryptd neither running nor on PATH, or with extraOptions.mongocryptdBypassSpawn incorrectly false; mongocryptd present but listening on a port that is firewalled or already in use.","commonSituations":"Missing mongodb-enterprise mongocryptd binary in PATH; Docker images that install the node driver but not mongocryptd; restricted environments that forbid spawning subprocesses; wrong mongocryptdURI/port.","solutions":["Install mongocryptd (part of mongodb-enterprise) and ensure its directory is on PATH, or set extraOptions.mongocryptdSpawnPath to its absolute location.","Start mongocryptd manually and point extraOptions.mongocryptdURI at its address, with mongocryptdBypassSpawn: true.","Install crypt_shared and either set cryptSharedLibRequired: true or let the driver prefer it; this removes the mongocryptd dependency entirely."],"exampleFix":"// before\nautoEncryption: {\n  extraOptions: {} // mongocryptd missing\n}\nawait client.connect(); // init() throws\n\n// after\nautoEncryption: {\n  extraOptions: {\n    mongocryptdBypassSpawn: true,\n    mongocryptdURI: 'mongodb://localhost:27020'\n  }\n}","handlingStrategy":"fallback","validationCode":"// Verify mongocryptd is reachable before connecting the client\nconst { MongoClient } = require('mongodb');\nasync function mongocryptdUp(uri) {\n  const probe = new MongoClient(uri, { serverSelectionTimeoutMS: 2000 });\n  try { await probe.connect(); return true; } catch { return false; } finally { await probe.close().catch(()=>{}); }\n}","typeGuard":"// Not applicable: process/environment availability, not a type.","tryCatchPattern":"try { await client.connect(); }\ncatch (err) {\n  if (err instanceof MongoRuntimeError && /Unable to connect to `mongocryptd`/.test(err.message)) {\n    /* start mongocryptd, fix PATH, or switch to crypt_shared */\n  } else throw err;\n}","preventionTips":["Install mongocryptd and put its directory on PATH, or set mongocryptdSpawnPath.","Prefer crypt_shared to remove the mongocryptd dependency entirely.","Use mongocryptdBypassSpawn: true with a pre-started mongocryptd in containers."],"tags":["csfle","mongocryptd","deployment","native-library","startup"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}