{"record":{"id":"9b0d67146f7f91b8","repo":"apache/pulsar","slug":"error-during-schema-compatibility-check-with-strat","errorCode":null,"errorMessage":"Error during schema compatibility check with strategy ${strategy}: ${exceptionClassName}: ${message}","messagePattern":"Error during schema compatibility check with strategy (.+?): (.+?): (.+?)","errorType":"exception","errorClass":"IncompatibleSchemaException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/service/schema/AvroSchemaBasedCompatibilityCheck.java","lineNumber":72,"sourceCode":"            for (SchemaData schemaData : from) {\n                Schema.Parser parser =\n                        new Schema.Parser(StructSchemaDataValidator.COMPATIBLE_NAME_VALIDATOR);\n                parser.setValidateDefaults(false);\n                fromList.addFirst(parser.parse(new String(schemaData.getData(), UTF_8)));\n            }\n            Schema.Parser parser = new Schema.Parser(StructSchemaDataValidator.COMPATIBLE_NAME_VALIDATOR);\n            parser.setValidateDefaults(false);\n            Schema toSchema = parser.parse(new String(to.getData(), UTF_8));\n            SchemaValidator schemaValidator = createSchemaValidator(strategy);\n            schemaValidator.validate(toSchema, fromList);\n        } catch (SchemaParseException e) {\n            log.warn().exceptionMessage(e).log(\"Error during schema parsing\");\n            throw new IncompatibleSchemaException(e);\n        } catch (SchemaValidationException e) {\n            String msg = String.format(\"Error during schema compatibility check with strategy %s: %s: %s\",\n                    strategy, e.getClass().getName(), e.getMessage());\n            log.warn(msg);\n            throw new IncompatibleSchemaException(msg, e);\n        }\n    }\n\n    static SchemaValidator createSchemaValidator(SchemaCompatibilityStrategy compatibilityStrategy) {\n        final SchemaValidatorBuilder validatorBuilder = new SchemaValidatorBuilder();\n        switch (compatibilityStrategy) {\n            case BACKWARD_TRANSITIVE:\n                return createLatestOrAllValidator(validatorBuilder.canReadStrategy(), false);\n            case BACKWARD:\n                return createLatestOrAllValidator(validatorBuilder.canReadStrategy(), true);\n            case FORWARD_TRANSITIVE:\n                return createLatestOrAllValidator(validatorBuilder.canBeReadStrategy(), false);\n            case FORWARD:\n                return createLatestOrAllValidator(validatorBuilder.canBeReadStrategy(), true);\n            case FULL_TRANSITIVE:\n                return createLatestOrAllValidator(validatorBuilder.mutualReadStrategy(), false);\n            case FULL:\n                return createLatestOrAllValidator(validatorBuilder.mutualReadStrategy(), true);","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/service/schema/AvroSchemaBasedCompatibilityCheck.java#L54-L90","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// validate the schema standalone before submitting\nSchema.Parser parser = new Schema.Parser();\nSchema schema = parser.parse(schemaJson); // throws if malformed\nSchemaValidator validator = new SchemaValidatorBuilder()\n    .validityStrategy().build();\nvalidator.validate(schema, List.of(existingSchemas)); // pre-check on the client","typeGuard":null,"tryCatchPattern":"try {\n    checker.checkCompatible(schemaData, strategies, existingSchemas);\n} catch (IncompatibleSchemaException e) {\n    String msg = e.getMessage();\n    if (msg != null && msg.startsWith(\"Error during schema compatibility check with strategy\")) {\n        Throwable cause = e.getCause(); // SchemaValidationException — inspect for validator failure vs real incompatibility\n        log.warn(\"Schema compatibility check failed internally\", cause);\n    }\n    // surface a 4xx to the uploader with the cause summary\n}","preventionTips":["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"],"tags":["java","schema","avro","compatibility-check"],"backgroundTag":"schema-compatibility-check-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}