apache/flink · error · IllegalArgumentException

Could not load class for serialization config

Error message

Could not load class for serialization config

What it means

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.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/serialization/SerializerConfigImpl.java:368

    public void configure(ReadableConfig configuration, ClassLoader classLoader) {
        configuration.getOptional(PipelineOptions.GENERIC_TYPES).ifPresent(this::setGenericTypes);
        configuration.getOptional(PipelineOptions.FORCE_KRYO).ifPresent(this::setForceKryo);
        configuration.getOptional(PipelineOptions.FORCE_AVRO).ifPresent(this::setForceAvro);
        configuration
                .getOptional(PipelineOptions.FORCE_KRYO_AVRO)
                .ifPresent(this::setForceKryoAvro);
        configuration
                .getOptional(PipelineOptions.SERIALIZATION_CONFIG)
                .ifPresent(c -> parseSerializationConfigWithExceptionHandling(classLoader, c));
    }

    @SuppressWarnings("unchecked")
    private <T extends Class> T loadClass(
            String className, ClassLoader classLoader, String errorMessage) {
        try {
            return (T) Class.forName(className, false, classLoader);
        } catch (ClassNotFoundException e) {
            throw new IllegalArgumentException(errorMessage, e);
        }
    }

    private void parseSerializationConfigWithExceptionHandling(
            ClassLoader classLoader, List<String> serializationConfigs) {
        try {
            parseSerializationConfig(classLoader, serializationConfigs);
        } catch (Exception e) {
            throw new IllegalArgumentException(
                    String.format("Could not configure serializers from %s.", serializationConfigs),
                    e);
        }
    }

    private void parseSerializationConfig(
            ClassLoader classLoader, List<String> serializationConfigs) {
        final LinkedHashMap<Class<?>, Map<String, String>> serializationConfigByClass =
                serializationConfigs.stream()

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Verify the class name in serialization-config is spelled correctly (fully qualified).
2. Ensure the jar containing the class is on the job classpath (flink lib/ or --jar argument).
3. Run Class.forName manually in a test to confirm the class is resolvable with the deployed classpath.

Example fix

# before (class name wrong/missing)
pipeline.serialization-config: com.example.MyOldSerializerName

# after
pipeline.serialization-config: com.example.MyRenamedSerializerName
# Also: add the jar containing the class to the Flink job classpath

// Pre-validate that every class name in the config is loadable
for (String name : classNames) {
    try {
        Class.forName(name, false, getClass().getClassLoader());
    } catch (ClassNotFoundException e) {
        throw new IllegalArgumentException("Class not on classpath: " + name, e);
    }
}

// Inspect the cause chain when caught during job submission
try {
    env.execute();
} catch (Exception e) {
    Throwable cause = e;
    while (cause.getCause() != null) cause = cause.getCause();
    if (cause instanceof ClassNotFoundException) {
        // add the missing jar / fix the class name
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Bad syntax for classpath: {}
• Multiple compatible client factories found for: {}.
• No ClusterClientFactory found. If you were targeting a Yarn
• The program's entry point class '{className}' could not be l
• Unable to instantiate the hadoop input format

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/83b91960f42225e2. Report an issue: GitHub.