What causes "Unable to find value class." in apache/flink?

Include the value class (and its transitive dependencies) in the user-code jar submitted with the job.

apache/flink · critical · RuntimeException

Unable to find value class.

Error message

Unable to find value class.

What it means

Thrown during Java deserialization of HadoopInputFormatBase when readObject() cannot load the value class by name via Class.forName(valueClassName, true, contextClassLoader). Symmetric to the key-class failure: the value class name was serialized from the client and must be resolvable on every TaskManager.

Source

Thrown at flink-connectors/flink-hadoop-compatibility/src/main/java/org/apache/flink/api/java/hadoop/mapreduce/HadoopInputFormatBase.java:343

        try {
            this.keyClass =
                    (Class<K>)
                            Class.forName(
                                    keyClassName,
                                    true,
                                    Thread.currentThread().getContextClassLoader());
        } catch (Exception e) {
            throw new RuntimeException("Unable to find key class.", e);
        }
        try {
            this.valueClass =
                    (Class<V>)
                            Class.forName(
                                    valueClassName,
                                    true,
                                    Thread.currentThread().getContextClassLoader());
        } catch (Exception e) {
            throw new RuntimeException("Unable to find value class.", e);
        }
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

Include the value class (and its transitive dependencies) in the user-code jar submitted with the job.
If shading, ensure the value class's runtime name matches the serialized name.
Rebuild and resubmit the fat jar so the TaskManager classloader can resolve the value type.
Confirm the value class is public and loadable by the user-code classloader.

Defensive patterns

Strategy: validation

Validate before calling

// Verify the value class is resolvable on the runtime classpath before submitting
String valueName = valueClass.getName();
try {
    Class.forName(valueName, true, Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Value class " + valueName
        + " is not on the runtime classpath; ship it in the user-code jar", e);
}

Prevention

Include value classes (and transitive deps) in the submitted user-code jar.
Keep shading consistent so runtime names match serialized names.
Verify generated value classes (Avro/Protobuf) are packaged.
Match dependency versions across build and cluster.

When it happens

Trigger: Triggered on the TaskManager when Class.forName(valueClassName, true, contextClassLoader) fails during readObject() — e.g. the value class is missing from the shipped jar, was shaded/renamed, or the user-code classloader cannot resolve it.

Common situations: Custom Writable value type not in the submitted jar; value class relocated by shading; generated class (Avro/Protobuf/Thrift) omitted from the fat jar; dependency version mismatch where the value class package changed between build and runtime.

Related errors

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