{"record":{"id":"903aeda542172fbe","repo":"apache/pulsar","slug":"unknown-schemacompatibilitystrategy","errorCode":null,"errorMessage":"Unknown SchemaCompatibilityStrategy.","messagePattern":"Unknown SchemaCompatibilityStrategy\\.","errorType":"exception","errorClass":"IncompatibleSchemaException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/service/schema/ProtobufNativeSchemaCompatibilityCheck.java","lineNumber":55,"sourceCode":"\n    @Override\n    public void checkCompatible(SchemaData from, SchemaData to, SchemaCompatibilityStrategy strategy)\n            throws IncompatibleSchemaException {\n        Descriptor fromDescriptor = ProtobufNativeSchemaUtils.deserialize(from.getData());\n        Descriptor toDescriptor = ProtobufNativeSchemaUtils.deserialize(to.getData());\n        switch (strategy) {\n            case BACKWARD_TRANSITIVE:\n            case BACKWARD:\n            case FORWARD_TRANSITIVE:\n            case FORWARD:\n            case FULL_TRANSITIVE:\n            case FULL:\n                checkRootMessageChange(fromDescriptor, toDescriptor, strategy);\n                return;\n            case ALWAYS_COMPATIBLE:\n                return;\n            default:\n                throw new IncompatibleSchemaException(\"Unknown SchemaCompatibilityStrategy.\");\n        }\n    }\n\n    @Override\n    public void checkCompatible(Iterable<SchemaData> from, SchemaData to, SchemaCompatibilityStrategy strategy)\n            throws IncompatibleSchemaException {\n        for (SchemaData schemaData : from) {\n            checkCompatible(schemaData, to, strategy);\n        }\n    }\n\n    private void checkRootMessageChange(Descriptor fromDescriptor, Descriptor toDescriptor,\n                                            SchemaCompatibilityStrategy strategy) throws IncompatibleSchemaException {\n        if (!fromDescriptor.getFullName().equals(toDescriptor.getFullName())) {\n            throw new IncompatibleSchemaException(\"Protobuf root message change is not allowed under the '\"\n                    + strategy + \"' strategy. Original message name: '\" + fromDescriptor.getFullName()\n                    + \"', new message name: '\" + toDescriptor.getFullName() + \"'.\");\n        }","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/service/schema/ProtobufNativeSchemaCompatibilityCheck.java#L37-L73","documentation":"ProtobufNativeSchemaCompatibilityCheck handles BACKWARD, FORWARD, FULL and ALWAYS_COMPATIBLE strategies; any other strategy value falls through the switch's default branch and throws, because root-message comparison semantics are undefined for it.","triggerScenarios":"checkCompatible on a PROTOBUF_NATIVE schema with a SchemaCompatibilityStrategy other than BACKWARD/FORWARD/FULL/ALWAYS_COMPATIBLE — e.g. a strategy enum value added later (like NONE/UNDEFINED) reaching this checker.","commonSituations":"Namespace-level schemaCompatibilityStrategy set to a value not supported by the Protobuf Native checker; brokers with newer strategy enums interacting with older check implementations; misconfigured namespace policies.","solutions":["Set the namespace/topic schema compatibility strategy to FULL, BACKWARD, FORWARD, or ALWAYS_COMPATIBLE (FULL is the safest for Protobuf Native).","Upgrade Pulsar so the strategy set is consistent between broker components.","Check the namespace policy with admin.namespaces().getSchemaCompatibilityStrategy() before updating Protobuf Native schemas."],"exampleFix":"// before\nadmin.namespaces().setSchemaCompatibilityStrategy(ns, SchemaCompatibilityStrategy.UNDEFINED);\n// after\nadmin.namespaces().setSchemaCompatibilityStrategy(ns, SchemaCompatibilityStrategy.FULL);","handlingStrategy":"validation","validationCode":"SchemaCompatibilityStrategy s = admin.namespaces().getSchemaCompatibilityStrategy(ns);\nSet<SchemaCompatibilityStrategy> supported = EnumSet.of(BACKWARD, FORWARD, FULL, ALWAYS_COMPATIBLE);\nif (!supported.contains(s)) throw new IllegalStateException(\"Unsupported strategy for Protobuf Native: \" + s);","typeGuard":"boolean protobufNativeStrategySupported(SchemaCompatibilityStrategy s) {\n    return s == SchemaCompatibilityStrategy.BACKWARD || s == SchemaCompatibilityStrategy.FORWARD\n        || s == SchemaCompatibilityStrategy.FULL || s == SchemaCompatibilityStrategy.ALWAYS_COMPATIBLE;\n}","tryCatchPattern":"try {\n    admin.schemas().createSchema(topic, protoNativeSchemaInfo);\n} catch (PulsarAdminException e) {\n    if (e.getMessage().contains(\"Unknown SchemaCompatibilityStrategy\")) {\n        // set namespace strategy to FULL (or another supported value)\n    }\n}","preventionTips":["Use FULL compatibility for Protobuf Native topics by default.","Verify namespace strategy after any namespace policy migration.","Keep broker versions consistent across the cluster so strategy enums match.","Document the allowed strategy values for protobuf-native topics in team runbooks."],"tags":["pulsar","protobuf","compatibility-strategy"],"backgroundTag":"unsupported-compatibility-strategy","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}