{"record":{"id":"9a56a55a717abd3b","repo":"apache/flink","slug":"could-not-find-class-in-classpath-typeserial","errorCode":null,"errorMessage":"Could not find class '{}' in classpath. TypeSerializerConfigSnapshot and it's subclasses are not supported since Flink 1.17. If you are using built-in serializers, please first migrate to Flink 1.16. If you are using custom serializers, please migrate them to TypeSerializerSnapshot using Flink 1.16.","messagePattern":"Could not find class '(.+?)' in classpath\\. TypeSerializerConfigSnapshot and it's subclasses are not supported since Flink 1\\.17\\. If you are using built-in serializers, please first migrate to Flink 1\\.16\\. If you are using custom serializers, please migrate them to TypeSerializerSnapshot using Flink 1\\.16\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"flink-core/src/main/java/org/apache/flink/util/InstantiationUtil.java","lineNumber":669,"sourceCode":"     *     found, or the class is not a subtype of the given supertype class.\n     */\n    public static <T> Class<T> resolveClassByName(\n            DataInputView in, ClassLoader cl, Class<? super T> supertype) throws IOException {\n\n        final String className = in.readUTF();\n        final Class<?> rawClazz;\n        try {\n            rawClazz = Class.forName(className, false, cl);\n        } catch (ClassNotFoundException e) {\n            String error = \"Could not find class '\" + className + \"' in classpath.\";\n            if (className.contains(\"SerializerConfig\")) {\n                error +=\n                        \" TypeSerializerConfigSnapshot and it's subclasses are not supported since Flink 1.17.\"\n                                + \" If you are using built-in serializers, please first migrate to Flink 1.16.\"\n                                + \" If you are using custom serializers, please migrate them to\"\n                                + \" TypeSerializerSnapshot using Flink 1.16.\";\n            }\n            throw new IOException(error, e);\n        }\n\n        if (!supertype.isAssignableFrom(rawClazz)) {\n            throw new IOException(\n                    \"The class \" + className + \" is not a subclass of \" + supertype.getName());\n        }\n\n        @SuppressWarnings(\"unchecked\")\n        Class<T> clazz = (Class<T>) rawClazz;\n        return clazz;\n    }\n\n    // --------------------------------------------------------------------------------------------\n\n    /** Private constructor to prevent instantiation. */\n    private InstantiationUtil() {\n        throw new RuntimeException();\n    }","sourceCodeStart":651,"sourceCodeEnd":687,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/util/InstantiationUtil.java#L651-L687","documentation":"InstantiationUtil.resolveClassByName (used when restoring serializer snapshots from checkpoints/savepoints) could not load the class named in the checkpoint metadata via Class.forName. When the missing class name contains 'SerializerConfig', the message is extended: TypeSerializerConfigSnapshot and its subclasses were removed in Flink 1.17, so checkpoints written with the old snapshot format by pre-1.16 jobs cannot be restored on 1.17+.","triggerScenarios":"Restoring a checkpoint/savepoint whose state serializer snapshot references a class that is not on the classpath (Class.forName throws ClassNotFoundException). The long migration hint appears when className contains 'SerializerConfig', i.e. a pre-1.17 TypeSerializerConfigSnapshot class is referenced.","commonSituations":"Upgrading a job straight from Flink <=1.16 to 1.17+ and restoring an old checkpoint that stores TypeSerializerConfigSnapshot metadata; a user jar containing a custom serializer snapshot class was not attached on restore; class was renamed or shaded between application versions.","solutions":["If you jumped to Flink 1.17+ from a version <=1.16: restore the old checkpoint first on Flink 1.16 to let it migrate snapshots to TypeSerializerSnapshot, take a new checkpoint, then upgrade.","For custom serializers: port the serializer to implement TypeSerializerSnapshot (replacing TypeSerializerConfigSnapshot) while still on Flink 1.16, run a savepoint, then upgrade.","Ensure the jar containing the missing class is on the classpath of the job being restored (attach it via -C / pipeline.classpaths or bundle it in the user jar).","Verify the class name in the error against your project for renames/refactors and keep class names of snapshot classes stable across versions."],"exampleFix":"// before (custom serializer, pre-1.16 style)\npublic class MySerializerSnapshot<T> extends TypeSerializerConfigSnapshot<T> { ... }\n\n// after\npublic class MySerializerSnapshot<T> implements TypeSerializerSnapshot<T> {\n    @Override public int getCurrentVersion() { return 1; }\n    // readSnapshot/writeSnapshot/resolveSchemaCompatibility implemented\n}","handlingStrategy":"validation","validationCode":"// Before restore, confirm every snapshot class resolves on this classpath\nString cn = readSnapshotClassNameFromCheckpoint();\ntry {\n    Class.forName(cn, false, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Checkpoint references missing class \" + cn + \" - attach its jar or migrate via Flink 1.16\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    jobEnv.execute();\n} catch (IOException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Could not find class\")) {\n        // surface migration guidance instead of raw stack trace\n    }\n}","preventionTips":["Migrate serializers to TypeSerializerSnapshot on Flink 1.16 before upgrading to 1.17+","Always ship custom serializer/snapshot classes in the user jar on restore","Keep snapshot class names and packages stable across releases"],"tags":["checkpointing","restore","upgrade","migration","classloader","serialization"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}