apache/pulsar · error · IncompatibleSchemaException

Key schemas or Value schemas are different schema type, from

Error message

Key schemas or Value schemas are different schema type, from key schema type is %s and to key schema is %s, from value schema is %s and to value schema is %s

What it means

Once both sides are KEY_VALUE schemas, their inner key and value schema types must match exactly (e.g. key AVRO + value AVRO on both sides). If either the key schema type or the value schema type differs between the stored schema and the new schema, the update is rejected with a formatted message listing all four types.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/schema/KeyValueSchemaCompatibilityCheck.java:85

            return;
        }
        if (to.getType() != SchemaType.KEY_VALUE) {
            throw new IncompatibleSchemaException("To schema is not a KEY_VALUE schema.");
        }
        LinkedList<SchemaData> fromKeyList = new LinkedList<>();
        LinkedList<SchemaData> fromValueList = new LinkedList<>();
        KeyValue<SchemaData, SchemaData> fromKeyValue;
        KeyValue<SchemaData, SchemaData> toKeyValue = decodeKeyValueSchemaData(to);
        SchemaType toKeyType = toKeyValue.getKey().getType();
        SchemaType toValueType = toKeyValue.getValue().getType();

        for (SchemaData schemaData : from) {
            if (schemaData.getType() != SchemaType.KEY_VALUE) {
                throw new IncompatibleSchemaException("From schema is not a KEY_VALUE schema.");
            }
            fromKeyValue = decodeKeyValueSchemaData(schemaData);
            if (fromKeyValue.getKey().getType() != toKeyType || fromKeyValue.getValue().getType() != toValueType) {
                throw new IncompatibleSchemaException(
                        String.format("Key schemas or Value schemas are different schema type, "
                                        + "from key schema type is %s and to key schema is %s,"
                                        + " from value schema is %s and to value schema is %s",
                                fromKeyValue.getKey().getType(),
                                toKeyType,
                                fromKeyValue.getValue().getType(),
                                toValueType));
            }
            fromKeyList.addFirst(fromKeyValue.getKey());
            fromValueList.addFirst(fromKeyValue.getValue());
        }
        SchemaCompatibilityCheck keyCheck = checkers.getOrDefault(toKeyType, SchemaCompatibilityCheck.DEFAULT);
        SchemaCompatibilityCheck valueCheck = checkers.getOrDefault(toValueType, SchemaCompatibilityCheck.DEFAULT);
        keyCheck.checkCompatible(fromKeyList, toKeyValue.getKey(), strategy);
        valueCheck.checkCompatible(fromValueList, toKeyValue.getValue(), strategy);
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Align the key and value schema types with the existing topic schema (inspect via admin.schemas() to see current types).
2. If the type change is intentional, delete the topic schema and re-create it with the new KeyValue configuration.
3. Standardize the KeyValue schema definition in a shared library used by all producers/consumers.

Example fix

// before
Schema.KeyValue(Schema.STRING, Schema.AVRO(Value.class)) // topic was KV(AVRO, AVRO)
// after
Schema.KeyValue(Schema.AVRO(Key.class), Schema.AVRO(Value.class))

SchemaInfo existing = admin.schemas().getSchemaInfo(topic);
// decode existing KV schema types and compare to the planned one before upload
KeyValue<SchemaType, SchemaType> planned = KeyValue.of(SchemaType.AVRO, SchemaType.AVRO);
// existing types come from decoding existing.getSchemaData(); abort if they differ from planned

boolean kvTypesMatch(SchemaType fromKey, SchemaType toKey, SchemaType fromVal, SchemaType toVal) {
    return fromKey == toKey && fromVal == toVal;
}

try {
    admin.schemas().createSchema(topic, kvSchemaInfo);
} catch (PulsarAdminException e) {
    if (e.getMessage().startsWith("Key schemas or Value schemas are different schema type")) {
        // align key/value schema types with the existing topic schema
    }
}

When it happens

Trigger: checkCompatible where fromKeyValue.getKey().getType() != toKeyType or fromKeyValue.getValue().getType() != toValueType after decoding both KeyValue schema payloads.

Common situations: Producers switching from Schema.KeyValue(AVRO, AVRO) to Schema.KeyValue(STRING, AVRO) or KeyValue(JSON, JSON) on the same topic; mixed client configurations across services.

Related errors

• To schema is not a KEY_VALUE schema.
• From schema is not a KEY_VALUE schema.
• RestException(conversionError)
• External schema is not compatible with the other schema type
• payload (${payloadSize} bytes) cannot be decoded with schema

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/944c7ddbac7dde78. Report an issue: GitHub.