mongodb/node-mongodb-native · error · MongoRuntimeError

Unable to connect to `mongocryptd`, please make sure it is r

Error message

Unable to connect to `mongocryptd`, please make sure it is running or in your PATH for auto-spawn

What it means

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.

Source

Thrown at src/client-side-encryption/auto_encrypter.ts:390

      throw new MongoRuntimeError(
        'Reached impossible state: mongocryptdManager is undefined when neither bypassSpawn nor the shared lib are specified.'
      );
    }
    if (!this._mongocryptdClient) {
      throw new MongoRuntimeError(
        'Reached impossible state: mongocryptdClient is undefined when neither bypassSpawn nor the shared lib are specified.'
      );
    }

    if (!this._mongocryptdManager.bypassSpawn) {
      await this._mongocryptdManager.spawn();
    }

    try {
      const client = await this._mongocryptdClient.connect();
      return client;
    } catch (error) {
      throw new MongoRuntimeError(
        'Unable to connect to `mongocryptd`, please make sure it is running or in your PATH for auto-spawn',
        { cause: error }
      );
    }
  }

  /**
   * Cleans up the `_mongocryptdClient`, if present.
   */
  async close(): Promise<void> {
    await this._mongocryptdClient?.close();
  }

  /**
   * Encrypt a command for a given namespace.
   */
  async encrypt(
    ns: string,

View on GitHub (pinned to 3366c21a63)

Solutions

1. Install mongocryptd (part of mongodb-enterprise) and ensure its directory is on PATH, or set extraOptions.mongocryptdSpawnPath to its absolute location.
2. Start mongocryptd manually and point extraOptions.mongocryptdURI at its address, with mongocryptdBypassSpawn: true.
3. Install crypt_shared and either set cryptSharedLibRequired: true or let the driver prefer it; this removes the mongocryptd dependency entirely.

Example fix

// before
autoEncryption: {
  extraOptions: {} // mongocryptd missing
}
await client.connect(); // init() throws

// after
autoEncryption: {
  extraOptions: {
    mongocryptdBypassSpawn: true,
    mongocryptdURI: 'mongodb://localhost:27020'
  }
}

// Verify mongocryptd is reachable before connecting the client
const { MongoClient } = require('mongodb');
async function mongocryptdUp(uri) {
  const probe = new MongoClient(uri, { serverSelectionTimeoutMS: 2000 });
  try { await probe.connect(); return true; } catch { return false; } finally { await probe.close().catch(()=>{}); }
}

// Not applicable: process/environment availability, not a type.

try { await client.connect(); }
catch (err) {
  if (err instanceof MongoRuntimeError && /Unable to connect to `mongocryptd`/.test(err.message)) {
    /* start mongocryptd, fix PATH, or switch to crypt_shared */
  } else throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• `cryptSharedLibRequired` set but no crypt_shared library loa
• Auto-encryption requested, but the module is not installed.
• Cannot set both proxyOptions and kmsConnectCallback
• Can only provide a custom AWS credential provider when the s
• Cannot set both proxyOptions and kmsConnectCallback

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