{"record":{"id":"1620dfa837b474d1","repo":"mongodb/node-mongodb-native","slug":"unreachable-state-machine-state-entered-mongocryp-1620df","errorCode":null,"errorMessage":"unreachable state machine state: entered MONGOCRYPT_CTX_NEED_MONGO_MARKINGS but mongocryptdClient is undefined","messagePattern":"unreachable state machine state: entered MONGOCRYPT_CTX_NEED_MONGO_MARKINGS but mongocryptdClient is undefined","errorType":"exception","errorClass":"MongoCryptError","httpStatus":null,"severity":"critical","filePath":"src/client-side-encryption/state_machine.ts","lineNumber":223,"sourceCode":"          );\n\n          for await (const collInfo of collInfoCursor) {\n            context.addMongoOperationResponse(serialize(collInfo));\n            if (getState() === MONGOCRYPT_CTX_ERROR) break;\n          }\n\n          if (getState() === MONGOCRYPT_CTX_ERROR) break;\n\n          context.finishMongoOperation();\n          break;\n        }\n\n        case MONGOCRYPT_CTX_NEED_MONGO_MARKINGS: {\n          const command = context.nextMongoOperation();\n          if (getState() === MONGOCRYPT_CTX_ERROR) break;\n\n          if (!mongocryptdClient) {\n            throw new MongoCryptError(\n              'unreachable state machine state: entered MONGOCRYPT_CTX_NEED_MONGO_MARKINGS but mongocryptdClient is undefined'\n            );\n          }\n\n          // When we are using the shared library, we don't have a mongocryptd manager.\n          const markedCommand: Uint8Array = mongocryptdManager\n            ? await mongocryptdManager.withRespawn(\n                this.markCommand.bind(this, mongocryptdClient, context.ns, command, options)\n              )\n            : await this.markCommand(mongocryptdClient, context.ns, command, options);\n\n          context.addMongoOperationResponse(markedCommand);\n          context.finishMongoOperation();\n          break;\n        }\n\n        case MONGOCRYPT_CTX_NEED_MONGO_KEYS: {\n          const filter = context.nextMongoOperation();","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/client-side-encryption/state_machine.ts#L205-L241","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure mongocryptd is installed and reachable, or install crypt_shared (the shared library) so mongocryptd is not required.","Verify mongocryptd is running: it listens on localhost:27020 by default; check `mongocryptd --version` and that the port is free.","Align driver, mongodb-client-encryption, and crypt_shared/mongocryptd versions per the CSFLE compatibility matrix.","If you intentionally bypass query analysis (mongocryptdBypassQueryAnalysis), ensure your usage doesn't require marking — otherwise this state is unreachable."],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install mongocryptd on PATH or use crypt_shared so the marking state can be served.","Confirm mongocryptd can bind localhost:27020.","Align driver and libmongocrypt/crypt_shared versions."],"tags":["csfle","client-side-encryption","mongocryptd","internal","version-skew"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}