{"record":{"id":"1ab4360accdd3429","repo":"apache/flink","slug":"unable-to-find-key-class","errorCode":null,"errorMessage":"Unable to find key class.","messagePattern":"Unable to find key class\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"flink-connectors/flink-hadoop-compatibility/src/main/java/org/apache/flink/api/java/hadoop/mapred/HadoopInputFormatBase.java","lineNumber":309,"sourceCode":"            this.mapredInputFormat =\n                    (org.apache.hadoop.mapred.InputFormat<K, V>)\n                            Class.forName(\n                                            hadoopInputFormatClassName,\n                                            true,\n                                            Thread.currentThread().getContextClassLoader())\n                                    .newInstance();\n        } catch (Exception e) {\n            throw new RuntimeException(\"Unable to instantiate the hadoop input format\", e);\n        }\n        try {\n            this.keyClass =\n                    (Class<K>)\n                            Class.forName(\n                                    keyClassName,\n                                    true,\n                                    Thread.currentThread().getContextClassLoader());\n        } catch (Exception e) {\n            throw new RuntimeException(\"Unable to find key class.\", e);\n        }\n        try {\n            this.valueClass =\n                    (Class<V>)\n                            Class.forName(\n                                    valueClassName,\n                                    true,\n                                    Thread.currentThread().getContextClassLoader());\n        } catch (Exception e) {\n            throw new RuntimeException(\"Unable to find value class.\", e);\n        }\n        ReflectionUtils.setConf(mapredInputFormat, jobConf);\n\n        jobConf.getCredentials().addAll(this.credentials);\n        Credentials currentUserCreds = getCredentialsFromUGI(UserGroupInformation.getCurrentUser());\n        if (currentUserCreds != null) {\n            jobConf.getCredentials().addAll(currentUserCreds);\n        }","sourceCodeStart":291,"sourceCodeEnd":327,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-connectors/flink-hadoop-compatibility/src/main/java/org/apache/flink/api/java/hadoop/mapred/HadoopInputFormatBase.java#L291-L327","documentation":"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.","triggerScenarios":"Restoring or deploying a HadoopInputFormat job where the key type class (e.g. org.apache.hadoop.io.Text) is not on the task classpath.","commonSituations":"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.","solutions":["Include the JAR containing the key class in the Flink job submission classpath.","If using a custom key type, ensure it is in the fat JAR or provided via -C.","Check the wrapped exception for the exact class name that failed to load.","Verify classloader settings (classloader.resolve-order) if the class exists but is shadowed."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Validate key class is on the classpath before job submission\ntry {\n    Class.forName(keyClassName, false, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException e) {\n    throw new IllegalArgumentException(\n        \"Key class not on classpath: \" + keyClassName + \". Add the required JAR.\", e);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Include the JAR with the key type class in the job submission.","For custom key types, package them in the fat JAR.","Validate class resolution locally before deploying."],"tags":["hadoop-compatibility","input-format","classpath","class-loading"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}