{"record":{"id":"12a66f60a186b0b1","repo":"apache/flink","slug":"unable-to-find-the-class-s-which-is-used-to-des","errorCode":null,"errorMessage":"Unable to find the class '%s' which is used to deserialize the elements of this serializer. Were the class was moved or renamed?","messagePattern":"Unable to find the class '(.+?)' which is used to deserialize the elements of this serializer\\. Were the class was moved or renamed\\?","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"flink-formats/flink-avro/src/main/java/org/apache/flink/formats/avro/typeutils/AvroSerializerSnapshot.java","lineNumber":236,"sourceCode":"            @SuppressWarnings(\"unchecked\")\n            SpecificData d =\n                    AvroFactory.getSpecificDataForClass(\n                            (Class<? extends SpecificData>) runtimeType, cl);\n            return AvroFactory.extractAvroSpecificSchema(runtimeType, d);\n        }\n        ReflectData d = new ReflectData(cl);\n        return d.getSchema(runtimeType);\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    @Nonnull\n    private static <T> Class<T> findClassOrThrow(\n            ClassLoader userCodeClassLoader, String className) {\n        try {\n            Class<?> runtimeTarget = Class.forName(className, false, userCodeClassLoader);\n            return (Class<T>) runtimeTarget;\n        } catch (ClassNotFoundException e) {\n            throw new IllegalStateException(\n                    \"\"\n                            + \"Unable to find the class '\"\n                            + className\n                            + \"' which is used to deserialize \"\n                            + \"the elements of this serializer. \"\n                            + \"Were the class was moved or renamed?\",\n                    e);\n        }\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    @Nonnull\n    private static <T> Class<T> findClassOrFallbackToGeneric(\n            ClassLoader userCodeClassLoader, String className) {\n        try {\n            Class<?> runtimeTarget = Class.forName(className, false, userCodeClassLoader);\n            return (Class<T>) runtimeTarget;\n        } catch (ClassNotFoundException e) {","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-formats/flink-avro/src/main/java/org/apache/flink/formats/avro/typeutils/AvroSerializerSnapshot.java#L218-L254","documentation":"IllegalStateException from AvroSerializerSnapshot.findClassOrThrow when Class.forName cannot load the Avro record class (or SpecificRecord) referenced by the restored state. The serializer snapshot stores the runtime class name; on restore it must be loadable from the user code classloader of the restored job.","triggerScenarios":"Restoring a savepoint after the Avro generated record class was renamed, moved to another package, or removed from the job jar; running with a fat jar that shades/relocates the record class.","commonSituations":"Refactoring generated Avro classes between job versions; maven-shade relocation of avro generated packages; the class living in a dependency not packaged into the application jar.","solutions":["Keep the fully-qualified class name of Avro records stable across job versions (regenerate code into the same package).","Repackage the jar so the record class is included on the user classpath and not shaded away.","If rename is unavoidable, perform a state migration (savepoint processor API) instead of direct restore."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// before restore, verify the record class is on the job classpath\nClass<?> c = Class.forName(\"com.acme.avro.User\", false, getUserClassloader());\nif (!org.apache.avro.specific.SpecificRecordBase.class.isAssignableFrom(c)) {\n    throw new IllegalStateException(\"Restored Avro class is not a SpecificRecord\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    env.execute();\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"Unable to find the class\")) {\n        // class moved/missing from jar; fix packaging or class name, then restore again\n        log.error(\"Avro record class missing on user classpath: {}\", e.getCause().getMessage());\n    }\n    throw e;\n}","preventionTips":["Freeze the package name of generated Avro classes across job versions.","Add a CI check that the fat jar contains every class named in the state's serializer snapshots.","Avoid shading/relocating generated Avro record packages in stateful jobs."],"tags":["avro","state-restore","classloader","class-not-found","flink"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}