mongodb/node-mongodb-native · error · MongoCompatibilityError

Driver support of Queryable Encryption is incompatible with

Error message

Driver support of Queryable Encryption is incompatible with server. Upgrade server to use Queryable Encryption. The minimum server version required is 7.0

What it means

Thrown when creating a collection that has encryptedFields (Queryable Encryption / FLE 2) against a server whose wire protocol version is below the minimum required for Queryable Encryption (server < 7.0). The driver detects the incompatibility in buildCommandDocument and raises MongoCompatibilityError, directing the user to upgrade. This protects against silently sending unsupported commands.

Source

Thrown at src/operations/create_collection.ts:169

  const timeoutContext = TimeoutContext.create({
    session: options.session,
    serverSelectionTimeoutMS: db.client.s.options.serverSelectionTimeoutMS,
    waitQueueTimeoutMS: db.client.s.options.waitQueueTimeoutMS,
    timeoutMS: options.timeoutMS
  });

  const encryptedFields: Document | undefined =
    options.encryptedFields ??
    db.client.s.options.autoEncryption?.encryptedFieldsMap?.[`${db.databaseName}.${name}`];

  if (encryptedFields) {
    class CreateSupportingFLEv2CollectionOperation extends CreateCollectionOperation {
      override buildCommandDocument(connection: Connection, session?: ClientSession): Document {
        if (
          !connection.description.loadBalanced &&
          maxWireVersion(connection) < MIN_SUPPORTED_QE_WIRE_VERSION
        ) {
          throw new MongoCompatibilityError(
            `${INVALID_QE_VERSION} The minimum server version required is ${MIN_SUPPORTED_QE_SERVER_VERSION}`
          );
        }

        return super.buildCommandDocument(connection, session);
      }
    }

    // Create auxilliary collections for queryable encryption support.
    const escCollection = encryptedFields.escCollection ?? `enxcol_.${name}.esc`;
    const ecocCollection = encryptedFields.ecocCollection ?? `enxcol_.${name}.ecoc`;

    for (const collectionName of [escCollection, ecocCollection]) {
      const createOp = new CreateSupportingFLEv2CollectionOperation(db, collectionName, {
        clusteredIndex: {
          key: { _id: 1 },
          unique: true
        },

View on GitHub (pinned to 3366c21a63)

Solutions

1. Upgrade the MongoDB server to 7.0 or newer before using Queryable Encryption.
2. Verify the server version with await db.admin().serverStatus() / hello() and ensure featureCompatibilityVersion >= 7.0.
3. If encryption is optional for this collection, remove the encryptedFields option / encryptedFieldsMap entry when targeting older servers.

Example fix

// before (server < 7.0)
await db.createCollection('patients', {
  encryptedFields: { fields: [...] }
}); // throws

// after
// 1. Upgrade mongod to >= 7.0, then:
await db.createCollection('patients', {
  encryptedFields: { fields: [...] }
});
// 2. Or omit encryptedFields on legacy servers.

const MIN_QE = 7.0;
async function assertQeSupported(db) {
  const { version } = (await db.command('hello')).forEach ?? (await db.admin().serverInfo());
  const major = Number(String(version ?? (await db.admin().buildInfo()).version).split('.')[0]);
  if (major < MIN_QE) throw new Error('Server < 7.0, QE unsupported');
}

function isQeCapable(wireVersion): boolean {
  return wireVersion >= 21; // min wire version for Queryable Encryption
}

When it happens

Trigger: Calling db.createCollection(name, { encryptedFields: {...} }) (or having an autoEncryption.encryptedFieldsMap entry for the collection) while connected to a MongoDB server older than 7.0. Also triggered by Atlas proxy/wire-version downgrades.

Common situations: Developing Queryable Encryption locally against an older mongod; connecting to a legacy on-prem deployment; mismatched server version in CI vs production; using a shared cluster below 7.0.

Related errors

• Unable to create collection: ${cause.message}
• Malformed JSON body in GET request.
• Unable to complete request.
• Malformed response body - missing field `access_token`.
• Malformed response body - missing field `expires_in`.

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/7e1c7d79d4b5eec2.json. Report an issue: GitHub.