{"record":{"id":"83b91960f42225e2","repo":"apache/flink","slug":"could-not-load-class-for-serialization-config","errorCode":null,"errorMessage":"Could not load class for serialization config","messagePattern":"Could not load class for serialization config","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/api/common/serialization/SerializerConfigImpl.java","lineNumber":368,"sourceCode":"    public void configure(ReadableConfig configuration, ClassLoader classLoader) {\n        configuration.getOptional(PipelineOptions.GENERIC_TYPES).ifPresent(this::setGenericTypes);\n        configuration.getOptional(PipelineOptions.FORCE_KRYO).ifPresent(this::setForceKryo);\n        configuration.getOptional(PipelineOptions.FORCE_AVRO).ifPresent(this::setForceAvro);\n        configuration\n                .getOptional(PipelineOptions.FORCE_KRYO_AVRO)\n                .ifPresent(this::setForceKryoAvro);\n        configuration\n                .getOptional(PipelineOptions.SERIALIZATION_CONFIG)\n                .ifPresent(c -> parseSerializationConfigWithExceptionHandling(classLoader, c));\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    private <T extends Class> T loadClass(\n            String className, ClassLoader classLoader, String errorMessage) {\n        try {\n            return (T) Class.forName(className, false, classLoader);\n        } catch (ClassNotFoundException e) {\n            throw new IllegalArgumentException(errorMessage, e);\n        }\n    }\n\n    private void parseSerializationConfigWithExceptionHandling(\n            ClassLoader classLoader, List<String> serializationConfigs) {\n        try {\n            parseSerializationConfig(classLoader, serializationConfigs);\n        } catch (Exception e) {\n            throw new IllegalArgumentException(\n                    String.format(\"Could not configure serializers from %s.\", serializationConfigs),\n                    e);\n        }\n    }\n\n    private void parseSerializationConfig(\n            ClassLoader classLoader, List<String> serializationConfigs) {\n        final LinkedHashMap<Class<?>, Map<String, String>> serializationConfigByClass =\n                serializationConfigs.stream()","sourceCodeStart":350,"sourceCodeEnd":386,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/common/serialization/SerializerConfigImpl.java#L350-L386","documentation":"Thrown by the private loadClass helper when Class.forName fails during parsing of the pipeline.serialization-config option. Each serialization config entry maps a class name to a serializer; if the named class cannot be found on the classpath, this IllegalArgumentException (wrapping ClassNotFoundException) is raised. It typically surfaces indirectly through the 'Could not configure serializers' wrapper, but can appear directly if loadClass is invoked standalone.","triggerScenarios":"Setting pipeline.serialization-config with a class name that is misspelled, not on the classpath, or not yet loaded. The parseSerializationConfig method calls loadClass for each key in the config map, triggering this when Class.forName throws ClassNotFoundException.","commonSituations":"Deploying a job whose jar is missing a dependency referenced in serialization-config; upgrading a dependency that renamed a class; typo in the configured class name string.","solutions":["Verify the class name in serialization-config is spelled correctly (fully qualified).","Ensure the jar containing the class is on the job classpath (flink lib/ or --jar argument).","Run Class.forName manually in a test to confirm the class is resolvable with the deployed classpath."],"exampleFix":"# before (class name wrong/missing)\npipeline.serialization-config: com.example.MyOldSerializerName\n\n# after\npipeline.serialization-config: com.example.MyRenamedSerializerName\n# Also: add the jar containing the class to the Flink job classpath","handlingStrategy":"validation","validationCode":"// Pre-validate that every class name in the config is loadable\nfor (String name : classNames) {\n    try {\n        Class.forName(name, false, getClass().getClassLoader());\n    } catch (ClassNotFoundException e) {\n        throw new IllegalArgumentException(\"Class not on classpath: \" + name, e);\n    }\n}","typeGuard":null,"tryCatchPattern":"// Inspect the cause chain when caught during job submission\ntry {\n    env.execute();\n} catch (Exception e) {\n    Throwable cause = e;\n    while (cause.getCause() != null) cause = cause.getCause();\n    if (cause instanceof ClassNotFoundException) {\n        // add the missing jar / fix the class name\n    }\n}","preventionTips":["Ensure all classes referenced in serialization-config are in the deployed job jar.","Validate class names with Class.forName in a unit/integration test before deploying.","Keep serialization-config under version control and review it on dependency upgrades."],"tags":["serialization","configuration","classpath","class-loading"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}