mongodb/node-mongodb-native · critical · MongoRuntimeError

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

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() 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.

Solutions

  1. Install mongocryptd and ensure it is in the system PATH for auto-spawn
  2. Start mongocryptd manually before connecting: mongocryptd --logpath /tmp/mongocryptd.log
  3. Install and use the crypt_shared library instead of mongocryptd (set cryptSharedLibPath or ensure it is on the system path)
  4. If using Docker, include mongocryptd in the container image or run it as a sidecar

Example fix

// before: no mongocryptd and no crypt_shared library
new MongoClient(uri, {
  autoEncryption: { kmsProviders: { ... } }
});
await client.connect(); // throws during init

// after: use crypt_shared library to avoid mongocryptd dependency
new MongoClient(uri, {
  autoEncryption: {
    extraOptions: { cryptSharedLibPath: '/usr/lib/mongo_crypt_v1.so' },
    kmsProviders: { ... }
  }
});
Defensive patterns

Strategy: retry

Validate before calling

// Check mongocryptd availability before connecting
const { MongoClient } = require('mongodb');
// Verify mongocryptd is running or in PATH
const { execSync } = require('child_process');
try {
  execSync('which mongocryptd', { stdio: 'ignore' });
} catch {
  console.warn('mongocryptd not found in PATH; install it or use crypt_shared library');
}

Try / catch

try {
  const client = new MongoClient(uri, { autoEncryption: config });
  await client.connect();
} catch (error) {
  if (error instanceof MongoRuntimeError && error.message.includes('mongocryptd')) {
    // Start mongocryptd or install crypt_shared library, then retry
  }
}

Prevention

When it happens

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

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

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/852f075d08324cc5. Report an issue: GitHub.

Appendix: 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 dce7939f86)