apache/pulsar · error · IncompatibleSchemaException

Error during schema compatibility check with strategy ${stra

Error message

Error during schema compatibility check with strategy ${strategy}: ${exceptionClassName}: ${message}

What it means

AvroSchemaBasedCompatibilityCheck.checkCompatible validates a schema against a compatibility strategy using Avro's SchemaValidator. If validation itself throws SchemaValidationException (a failure running the validator, e.g. malformed validator setup or an unexpected validation error distinct from an incompatibility verdict), it is wrapped in an IncompatibleSchemaException with a formatted message naming the strategy and the underlying exception class/message. The schema is rejected as incompatible and the original exception is the cause.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/schema/AvroSchemaBasedCompatibilityCheck.java:72

            for (SchemaData schemaData : from) {
                Schema.Parser parser =
                        new Schema.Parser(StructSchemaDataValidator.COMPATIBLE_NAME_VALIDATOR);
                parser.setValidateDefaults(false);
                fromList.addFirst(parser.parse(new String(schemaData.getData(), UTF_8)));
            }
            Schema.Parser parser = new Schema.Parser(StructSchemaDataValidator.COMPATIBLE_NAME_VALIDATOR);
            parser.setValidateDefaults(false);
            Schema toSchema = parser.parse(new String(to.getData(), UTF_8));
            SchemaValidator schemaValidator = createSchemaValidator(strategy);
            schemaValidator.validate(toSchema, fromList);
        } catch (SchemaParseException e) {
            log.warn().exceptionMessage(e).log("Error during schema parsing");
            throw new IncompatibleSchemaException(e);
        } catch (SchemaValidationException e) {
            String msg = String.format("Error during schema compatibility check with strategy %s: %s: %s",
                    strategy, e.getClass().getName(), e.getMessage());
            log.warn(msg);
            throw new IncompatibleSchemaException(msg, e);
        }
    }

    static SchemaValidator createSchemaValidator(SchemaCompatibilityStrategy compatibilityStrategy) {
        final SchemaValidatorBuilder validatorBuilder = new SchemaValidatorBuilder();
        switch (compatibilityStrategy) {
            case BACKWARD_TRANSITIVE:
                return createLatestOrAllValidator(validatorBuilder.canReadStrategy(), false);
            case BACKWARD:
                return createLatestOrAllValidator(validatorBuilder.canReadStrategy(), true);
            case FORWARD_TRANSITIVE:
                return createLatestOrAllValidator(validatorBuilder.canBeReadStrategy(), false);
            case FORWARD:
                return createLatestOrAllValidator(validatorBuilder.canBeReadStrategy(), true);
            case FULL_TRANSITIVE:
                return createLatestOrAllValidator(validatorBuilder.mutualReadStrategy(), false);
            case FULL:
                return createLatestOrAllValidator(validatorBuilder.mutualReadStrategy(), true);

View on GitHub (pinned to 820761864e)

Solutions

Read the wrapped cause (exceptionClassName:message in the message and getCause()) to find the actual SchemaValidationException
Fix the submitted schema (validate it standalone with avro-tools / SchemaValidator before uploading)
Verify the broker's Avro version matches the client that produced the schema (parse errors often mean version skew)
If the strategy name is wrong/unsupported for this check, correct the strategy and retry; check broker logs at warn level for the same message

Defensive patterns

Strategy: try-catch

Validate before calling

// validate the schema standalone before submitting
Schema.Parser parser = new Schema.Parser();
Schema schema = parser.parse(schemaJson); // throws if malformed
SchemaValidator validator = new SchemaValidatorBuilder()
    .validityStrategy().build();
validator.validate(schema, List.of(existingSchemas)); // pre-check on the client

Try / catch

try {
    checker.checkCompatible(schemaData, strategies, existingSchemas);
} catch (IncompatibleSchemaException e) {
    String msg = e.getMessage();
    if (msg != null && msg.startsWith("Error during schema compatibility check with strategy")) {
        Throwable cause = e.getCause(); // SchemaValidationException — inspect for validator failure vs real incompatibility
        log.warn("Schema compatibility check failed internally", cause);
    }
    // surface a 4xx to the uploader with the cause summary
}

Prevention

Parse and validate schemas with avro-tools before upload
Keep broker Avro library version consistent with schema producers
Log the cause chain — the strategy and underlying exception are embedded in the message
Distinguish validation crashes (SchemaValidationException) from genuine incompatibility verdicts when handling

When it happens

Trigger: Calling checkCompatible during schema upload/update when the Avro validation step throws SchemaValidationException — e.g. a validator built for an incompatible Avro library version, recursion issues, or a schema that crashes the validator rather than failing the comparison.

Common situations: Uploading a schema via the admin API with a compatibility strategy (BACKWARD/FORWARD/FULL and transitive variants) where Avro validation errors out; broker/avro version mismatch after an upgrade; pathological or deeply nested schemas tripping the validator.

Related errors

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