apache/flink · error · RuntimeException

Unable to find key class.

Error message

Unable to find key class.

What it means

Thrown by HadoopInputFormatBase.readFields when Class.forName(keyClassName) fails during deserialization. The key class name is serialized as part of the input format state; if the class is not resolvable on the restoring task's classpath, this RuntimeException wraps the ClassNotFoundException.

Source

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

            this.mapredInputFormat =
                    (org.apache.hadoop.mapred.InputFormat<K, V>)
                            Class.forName(
                                            hadoopInputFormatClassName,
                                            true,
                                            Thread.currentThread().getContextClassLoader())
                                    .newInstance();
        } catch (Exception e) {
            throw new RuntimeException("Unable to instantiate the hadoop input format", e);
        }
        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);
        }
        ReflectionUtils.setConf(mapredInputFormat, jobConf);

        jobConf.getCredentials().addAll(this.credentials);
        Credentials currentUserCreds = getCredentialsFromUGI(UserGroupInformation.getCurrentUser());
        if (currentUserCreds != null) {
            jobConf.getCredentials().addAll(currentUserCreds);
        }

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Include the JAR containing the key class in the Flink job submission classpath.
2. If using a custom key type, ensure it is in the fat JAR or provided via -C.
3. Check the wrapped exception for the exact class name that failed to load.
4. Verify classloader settings (classloader.resolve-order) if the class exists but is shadowed.

// Validate key class is on the classpath before job submission
try {
    Class.forName(keyClassName, false, Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException e) {
    throw new IllegalArgumentException(
        "Key class not on classpath: " + keyClassName + ". Add the required JAR.", e);
}

When it happens

Trigger: Restoring or deploying a HadoopInputFormat job where the key type class (e.g. org.apache.hadoop.io.Text) is not on the task classpath.

Common situations: Missing Hadoop common JAR; custom key class not included in the submitted JAR; key class moved or renamed between Hadoop versions; classpath isolation issue where the key class is in a parent classloader that is not visible.

Related errors

• Unable to instantiate the hadoop input format
• Unable to find value class.
• Unable to instantiate the hadoop output format
• The program's entry point class '{className}' could not be l
• Could not load class for serialization config

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