mongodb/node-mongodb-native · critical · MongoCryptError

unreachable state machine state: entered MONGOCRYPT_CTX_NEED

Error message

unreachable state machine state: entered MONGOCRYPT_CTX_NEED_MONGO_COLLINFO but metadata client is undefined

What it means

An internal 'this should never happen' guard in the CSFLE state machine. MONGOCRYPT_CTX_NEED_MONGO_COLLINFO means libmongocrypt wants collection metadata (JSONSchema, validation) to decide what to encrypt, but the executor has no metaDataClient. The metadata client is the application's MongoClient used for auto-discovery; it is only absent in certain explicit-encryption-only configurations.

Source

Thrown at src/client-side-encryption/state_machine.ts:195

    let result: Uint8Array | null = null;

    // Typescript treats getters just like properties: Once you've tested it for equality
    // it cannot change. Which is exactly the opposite of what we use state and status for.
    // Every call to at least `addMongoOperationResponse` and `finalize` can change the state.
    // These wrappers let us write code more naturally and not add compiler exceptions
    // to conditions checks inside the state machine.
    const getStatus = () => context.status;
    const getState = () => context.state;

    while (getState() !== MONGOCRYPT_CTX_DONE && getState() !== MONGOCRYPT_CTX_ERROR) {
      options.signal?.throwIfAborted();
      debug(`[context#${context.id}] ${stateToString.get(getState()) || getState()}`);

      switch (getState()) {
        case MONGOCRYPT_CTX_NEED_MONGO_COLLINFO: {
          const filter = deserialize(context.nextMongoOperation());
          if (!metaDataClient) {
            throw new MongoCryptError(
              'unreachable state machine state: entered MONGOCRYPT_CTX_NEED_MONGO_COLLINFO but metadata client is undefined'
            );
          }

          const collInfoCursor = this.fetchCollectionInfo(
            metaDataClient,
            context.ns,
            filter,
            options
          );

          for await (const collInfo of collInfoCursor) {
            context.addMongoOperationResponse(serialize(collInfo));
            if (getState() === MONGOCRYPT_CTX_ERROR) break;
          }

          if (getState() === MONGOCRYPT_CTX_ERROR) break;

View on GitHub (pinned to dce7939f86)

Solutions

1. Ensure the MongoClient used for autoEncryption is open and healthy and that keyVaultNamespace is set — the driver derives the metadata client from it.
2. Align versions: use compatible mongodb, mongodb-client-encryption, and libmongocrypt releases per the driver's CSFLE compatibility matrix.
3. If using explicit ClientEncryption only (no auto-encryption), make sure you are not triggering a code path that expects collection metadata (e.g. set schemaMap to avoid the collinfo lookup).
4. Report a bug with driver, mongodb-client-encryption, and libmongocrypt versions if the configuration is correct.

Example fix

// before: autoEncryption needs collinfo but no usable metadata client
new MongoClient(uri, {
  autoEncryption: {
    keyVaultNamespace: 'encryption.__keyVault',
    kmsProviders,
    // schemaMap missing and collection has no JSONSchema -> needs collinfo
  }
});
// after: provide a schemaMap so collinfo lookup is unnecessary
new MongoClient(uri, {
  autoEncryption: {
    keyVaultNamespace: 'encryption.__keyVault',
    kmsProviders,
    schemaMap: { 'db.coll': { bsonType: 'object', properties: { ssn: { encrypt: { ... } } } } }
  }
});

When it happens

Trigger: Auto-encryption that needs collection info but was constructed without a metaDataClient / keyVaultClient wired correctly; using a ClientEncryption (explicit) context where an auto-encryption context was expected; a driver bug or an incompatibility between driver and libmongocrypt versions causing an unexpected state transition.

Common situations: Version skew between mongodb driver, mongodb-client-encryption, and libmongocrypt; misconfigured AutoEncryption extraOptions; passing a closed/dereferenced MongoClient as the metaData client; custom StateMachine usage in tests.

Related errors

• unreachable state machine state: entered MONGOCRYPT_CTX_NEED
• Unknown state: ${getState()}
• unidentifiable error in MongoCrypt - received an error statu
• "options" cannot contain both "keyId" and "keyAltName"
• "options.keyAltName" must be of type string, but was of type

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