apache/pulsar · error · IncompatibleSchemaException

External schema is not compatible with the other schema type

Error message

External schema is not compatible with the other schema types.

What it means

The ExternalSchemaCompatibilityCheck rejects any compatibility comparison where exactly one of the two schemas (existing 'from' or new 'to') has SchemaType.EXTERNAL. An EXTERNAL schema carries data managed outside Pulsar's schema registry, so it can only be compared against another EXTERNAL schema; mixing it with AVRO, JSON, etc. is meaningless to the broker.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/schema/ExternalSchemaCompatibilityCheck.java:38

import org.apache.pulsar.broker.service.schema.exceptions.IncompatibleSchemaException;
import org.apache.pulsar.common.policies.data.SchemaCompatibilityStrategy;
import org.apache.pulsar.common.protocol.schema.SchemaData;
import org.apache.pulsar.common.schema.SchemaType;

public class ExternalSchemaCompatibilityCheck implements SchemaCompatibilityCheck {

    @Override
    public SchemaType getSchemaType() {
        return SchemaType.EXTERNAL;
    }

    @Override
    public void checkCompatible(SchemaData from, SchemaData to, SchemaCompatibilityStrategy strategy)
            throws IncompatibleSchemaException {
        if ((SchemaType.EXTERNAL.equals(from.getType()) || SchemaType.EXTERNAL.equals(to.getType()))
                && !from.getType().equals(to.getType())) {
            throw new IncompatibleSchemaException("External schema is not compatible with the other schema types.");
        }
    }

    @Override
    public void checkCompatible(Iterable<SchemaData> from, SchemaData to, SchemaCompatibilityStrategy strategy)
            throws IncompatibleSchemaException {
        for (SchemaData fromSchema : from) {
            checkCompatible(fromSchema, to, strategy);
        }
    }

}

View on GitHub (pinned to 820761864e)

Solutions

1. Make the new schema use the same SchemaType as the existing one — if the topic has an EXTERNAL schema, submit the update as EXTERNAL too.
2. If the topic should use a standard schema, delete the topic's schema first, then upload the new schema.
3. Audit the producer/consumer code so all clients agree on one schema type for the topic.

Example fix

// before: mixed types rejected
SchemaData from = SchemaDataImpl.builder().type(SchemaType.EXTERNAL)...;
SchemaData to = SchemaDataImpl.builder().type(SchemaType.AVRO)...;
check.checkCompatible(from, to, strategy);
// after: both sides same type
SchemaData to = SchemaDataImpl.builder().type(SchemaType.EXTERNAL)...;
check.checkCompatible(from, to, strategy);

if ((existing.getType() == SchemaType.EXTERNAL) != (incoming.getType() == SchemaType.EXTERNAL)) {
    throw new IllegalArgumentException("Cannot mix EXTERNAL schema with other schema types for this topic");
}
// proceed with update only when types agree

boolean bothExternalOrNeither(SchemaData a, SchemaData b) {
    return a.getType() == SchemaType.EXTERNAL == (b.getType() == SchemaType.EXTERNAL);
}

try {
    admin.schemas().createSchema(topic, schemaInfo);
} catch (PulsarAdminException e) {
    if (e.getMessage().contains("External schema is not compatible")) {
        // fix schema type or delete existing schema first
    }
}

When it happens

Trigger: Calling schemaRegistryManager/SchemaRegistryService.checkCompatible (directly or via updating a topic schema) when the existing stored schema is EXTERNAL and the new schema is not EXTERNAL, or vice versa, regardless of the SchemaCompatibilityStrategy.

Common situations: A topic previously configured with an external schema provider (e.g. via a custom SchemaData with type EXTERNAL) is updated with a normal AVRO/JSON schema; or a script uploads an EXTERNAL-type schema onto a topic that already has a standard schema; mixed client SDK versions posting different schema types to the same topic.

Related errors

• payload (${payloadSize} bytes) cannot be decoded with schema
• Can not enable for all producers but denies for replicators,
• Failed to add schema to an active topic with empty(BYTES) sc
• To schema is not a KEY_VALUE schema.
• From schema is not a KEY_VALUE schema.

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