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_MARKINGS but mongocryptdClient is undefined

What it means

Internal guard in the CSFLE state machine. MONGOCRYPT_CTX_NEED_MONGO_MARKINGS means libmongocrypt wants the command marked (encrypted) by mongocryptd (or the shared library), but the executor has no mongocryptdClient. mongocryptd is the sidecar process that annotates commands with encryption markings; it must be reachable.

Source

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

          );

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

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

          context.finishMongoOperation();
          break;
        }

        case MONGOCRYPT_CTX_NEED_MONGO_MARKINGS: {
          const command = context.nextMongoOperation();
          if (getState() === MONGOCRYPT_CTX_ERROR) break;

          if (!mongocryptdClient) {
            throw new MongoCryptError(
              'unreachable state machine state: entered MONGOCRYPT_CTX_NEED_MONGO_MARKINGS but mongocryptdClient is undefined'
            );
          }

          // When we are using the shared library, we don't have a mongocryptd manager.
          const markedCommand: Uint8Array = mongocryptdManager
            ? await mongocryptdManager.withRespawn(
                this.markCommand.bind(this, mongocryptdClient, context.ns, command, options)
              )
            : await this.markCommand(mongocryptdClient, context.ns, command, options);

          context.addMongoOperationResponse(markedCommand);
          context.finishMongoOperation();
          break;
        }

        case MONGOCRYPT_CTX_NEED_MONGO_KEYS: {
          const filter = context.nextMongoOperation();

View on GitHub (pinned to dce7939f86)

Solutions

1. Ensure mongocryptd is installed and reachable, or install crypt_shared (the shared library) so mongocryptd is not required.
2. Verify mongocryptd is running: it listens on localhost:27020 by default; check `mongocryptd --version` and that the port is free.
3. Align driver, mongodb-client-encryption, and crypt_shared/mongocryptd versions per the CSFLE compatibility matrix.
4. If you intentionally bypass query analysis (mongocryptdBypassQueryAnalysis), ensure your usage doesn't require marking — otherwise this state is unreachable.

When it happens

Trigger: Auto-encryption configured to use mongocryptd (not the shared library) but mongocryptd is not running / unreachable and the driver fell back to a null client; constructing the client with extraOptions.mongocryptdBypassQueryAnalysis and an incompatibility; version mismatch causing mongocryptdClient to be undefined.

Common situations: mongocryptd not installed or not on PATH; mongocryptd failed to start (port in use, e.g. 27020); the shared library (crypt_shared) is neither installed nor requested; driver/libmongocrypt/crypt_shared version skew.

Related errors

• unreachable state machine state: entered MONGOCRYPT_CTX_NEED
• Unknown state: ${getState()}
• unidentifiable error in MongoCrypt - received an error statu
• Unable to connect to `mongocryptd`, please make sure it is r
• "options" cannot contain both "keyId" and "keyAltName"

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