{"record":{"id":"4ba8a9b522501bb9","repo":"apache/incubator-seata","slug":"the-class-org-apache-seata-serializer-protobuf-pr","errorCode":null,"errorMessage":"The class 'org.apache.seata.serializer.protobuf.ProtobufSerializer' not found. Please manually reference 'org.apache.seata:seata-serializer-protobuf' dependency.","messagePattern":"The class 'org\\.apache\\.seata\\.serializer\\.protobuf\\.ProtobufSerializer' not found\\. Please manually reference 'org\\.apache\\.seata:seata-serializer-protobuf' dependency\\.","errorType":"exception","errorClass":"EnhancedServiceNotFoundException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/seata/core/serializer/SerializerServiceLoader.java","lineNumber":82,"sourceCode":"\n    private SerializerServiceLoader() {}\n\n    private static final String PROTOBUF_SERIALIZER_CLASS_NAME =\n            \"org.apache.seata.serializer.protobuf.ProtobufSerializer\";\n    private static final boolean CONTAINS_PROTOBUF_DEPENDENCY =\n            ReflectionUtil.isClassPresent(PROTOBUF_SERIALIZER_CLASS_NAME);\n\n    /**\n     * Load the service of {@link Serializer}\n     *\n     * @param type the serializer type\n     * @return the service of {@link Serializer}\n     * @throws EnhancedServiceNotFoundException the enhanced service not found exception\n     */\n    public static Serializer load(SerializerType type, byte version) throws EnhancedServiceNotFoundException {\n        // The following code is only used to kindly prompt users to add missing dependencies.\n        if (type == SerializerType.PROTOBUF && !CONTAINS_PROTOBUF_DEPENDENCY) {\n            throw new EnhancedServiceNotFoundException(\"The class '\" + PROTOBUF_SERIALIZER_CLASS_NAME + \"' not found. \"\n                    + \"Please manually reference 'org.apache.seata:seata-serializer-protobuf' dependency.\");\n        }\n\n        String serializerName = serializerKey(type, version);\n        String resolvedSerializerName = resolveSerializerName(serializerName);\n        if (!Objects.equals(serializerName, resolvedSerializerName)) {\n            LOGGER.info(\n                    \"Since {} is no longer maintained, This serialization extension has been replaced with {}.\",\n                    serializerName,\n                    resolvedSerializerName);\n        }\n        Serializer serializer = SERIALIZER_MAP.get(resolvedSerializerName);\n        if (serializer == null) {\n            if (type == SerializerType.SEATA) {\n                serializer = EnhancedServiceLoader.load(Serializer.class, type.name(), new Object[] {version});\n            } else {\n                serializer = EnhancedServiceLoader.load(Serializer.class, resolvedSerializerName);\n            }","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/apache/incubator-seata/blob/e01f97c6db397165050caa6764020410c2c8199a/core/src/main/java/org/apache/seata/core/serializer/SerializerServiceLoader.java#L64-L100","documentation":"SerializerServiceLoader.load(SerializerType, byte) throws EnhancedServiceNotFoundException when serialization type PROTOBUF is requested but the optional ProtobufSerializer class is not on the classpath (a cheap ReflectionUtil.isClassPresent check up front). Seata ships protobuf serialization as an optional module, so this error is a friendly directive to add the dependency rather than a real service-loading failure.","triggerScenarios":"Configuring seata.client/serialization (or server serialization) to protobuf via SerializerType.PROTOBUF and calling SerializerServiceLoader.load(...) — e.g. during client init, channel handler setup, or server codec bootstrap — without org.apache.seata:seata-serializer-protobuf in the dependencies.","commonSituations":"Setting serialization=protobuf after copying config from a project that had the extra jar; upgrading Seata and forgetting the previously-manual protobuf module; using seata-all (which does not bundle the protobuf serializer) and assuming all codecs are included.","solutions":["Add the dependency: `org.apache.seata:seata-serializer-protobuf` with the same version as the rest of Seata.","Restart the JVM after adding it — the presence check is static and only re-evaluated on class reload.","If protobuf was set by mistake, change serialization back to seata (the default) and no extra jar is needed.","Verify with `ReflectionUtil.isClassPresent(\"org.apache.seata.serializer.protobuf.ProtobufSerializer\")` in your environment if unsure."],"exampleFix":"<!-- before -->\n<dependency>\n  <groupId>org.apache.seata</groupId>\n  <artifactId>seata-all</artifactId>\n</dependency>\n<!-- serialization=protobuf in config -> EnhancedServiceNotFoundException -->\n\n<!-- after -->\n<dependency>\n  <groupId>org.apache.seata</groupId>\n  <artifactId>seata-serializer-protobuf</artifactId>\n  <version>${seata.version}</version>\n</dependency>","handlingStrategy":"validation","validationCode":"// before selecting protobuf serialization\nif (serializationType == SerializerType.PROTOBUF\n        && !io.seata.common.util.ReflectionUtil.isClassPresent(\"org.apache.seata.serializer.protobuf.ProtobufSerializer\")) {\n    throw new IllegalStateException(\n        \"serialization=protobuf requires the optional dependency org.apache.seata:seata-serializer-protobuf\");\n}\nSerializer s = SerializerServiceLoader.load(serializationType, version);","typeGuard":null,"tryCatchPattern":"try {\n    return SerializerServiceLoader.load(type, version);\n} catch (EnhancedServiceNotFoundException e) {\n    if (e.getMessage().contains(\"seata-serializer-protobuf\")) {\n        // dependency problem: degrade to default SEATA serializer if acceptable, else rethrow\n        return SerializerServiceLoader.load(SerializerType.SEATA, version);\n    }\n    throw e;\n}","preventionTips":["Add seata-serializer-protobuf in the same commit that flips serialization to protobuf.","Grep your builds for exclusions of seata-serializer-* modules.","Document in the project README which serialization each service uses."],"tags":["serialization","protobuf","dependency","configuration"],"backgroundTag":null,"analyzedSha":"e01f97c6db397165050caa6764020410c2c8199a","analyzedAt":"2026-08-14T10:23:53.097Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}