mongodb/node-mongodb-native · critical · MongoCryptError

Finalization error

Error message

Finalization error

What it means

Fallback message in the CSFLE state machine's MONGOCRYPT_CTX_READY branch: libmongocrypt's context.finalize() left the state in ERROR but context.status.message was empty, so the driver uses 'Finalization error'. Finalization is where the encrypted/decrypted bytes are produced; an error here usually means the crypto operation itself failed (bad key, bad algorithm, malformed ciphertext).

Source

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

        }

        case MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS: {
          const kmsProviders = await executor.askForKMSCredentials();
          context.provideKMSProviders(serialize(kmsProviders));
          break;
        }

        case MONGOCRYPT_CTX_NEED_KMS: {
          await Promise.all(this.requests(context, options));
          context.finishKMSRequests();
          break;
        }

        case MONGOCRYPT_CTX_READY: {
          const finalizedContext = context.finalize();
          if (getState() === MONGOCRYPT_CTX_ERROR) {
            const message = getStatus().message || 'Finalization error';
            throw new MongoCryptError(message);
          }
          result = finalizedContext;
          break;
        }

        default:
          throw new MongoCryptError(`Unknown state: ${getState()}`);
      }
    }

    if (getState() === MONGOCRYPT_CTX_ERROR || result == null) {
      const message = getStatus().message;
      if (!message) {
        debug(
          `unidentifiable error in MongoCrypt - received an error status from \`libmongocrypt\` but received no error message.`
        );
      }
      throw new MongoCryptError(

View on GitHub (pinned to dce7939f86)

Solutions

1. Ensure the data encryption key (DEK) referenced by keyId/keyAltName still exists in the key vault collection and can be unwrapped by the configured KMS.
2. Confirm the CMK in the KMS (AWS/Azure/GCP/local) is enabled and that the credentials have wrap/unwrap permission.
3. Match the encryption algorithm exactly between encrypt and decrypt; for Queryable Encryption, ensure queryType/contentionFactor/rangeOptions match what was used to encrypt.
4. Re-create the DEK if the CMK was rotated and the old key material is gone, then re-encrypt affected data.

try {
  await clientEncryption.decrypt(value);
} catch (e) {
  if (e instanceof MongoCryptError && /Finalization error/i.test(e.message)) {
    // verify the DEK exists and the CMK is enabled, then re-encrypt/retry
  }
  throw e;
}

When it happens

Trigger: Decrypting a value whose data key is missing or was created with a different KMS/CMK; encrypting with an algorithm/key combination libmongocrypt rejects; corrupted ciphertext; finalize of a context that was fed inconsistent data.

Common situations: Data key was deleted or rotated and old ciphertext can't be unwrapped; CMK in the KMS was disabled/rotated; algorithm mismatch between encrypt and decrypt (e.g. Random vs Deterministic); range/queryable-encryption options incompatible with the key material.

Related errors

• Malformed JSON body in GET request.
• Cannot set both proxyOptions and kmsConnectCallback
• Can only provide a custom AWS credential provider when the s
• Cannot set both proxyOptions and kmsConnectCallback
• Can only provide a custom AWS credential provider when the s

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