{"record":{"id":"5719f69280e6efd2","repo":"apache/flink","slug":"unable-to-find-key-class-5719f6","errorCode":null,"errorMessage":"Unable to find key class.","messagePattern":"Unable to find key class\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"flink-connectors/flink-hadoop-compatibility/src/main/java/org/apache/flink/api/java/hadoop/mapreduce/HadoopInputFormatBase.java","lineNumber":333,"sourceCode":"            this.mapreduceInputFormat =\n                    (org.apache.hadoop.mapreduce.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    }\n}\n","sourceCodeStart":315,"sourceCodeEnd":347,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-connectors/flink-hadoop-compatibility/src/main/java/org/apache/flink/api/java/hadoop/mapreduce/HadoopInputFormatBase.java#L315-L347","documentation":"Thrown during Java deserialization of HadoopInputFormatBase when readObject() cannot load the key class by name via Class.forName(keyClassName, true, contextClassLoader). The key class name was serialized from the client; if the TaskManager classloader cannot resolve it, deserialization fails with this RuntimeException and the task cannot start.","triggerScenarios":"Triggered on the TaskManager when Class.forName(keyClassName, true, contextClassLoader) fails during readObject() — e.g. the key class is not on the TaskManager classpath, was shaded/renamed, or the user jar shipping it was not attached to the job.","commonSituations":"Custom Writable key type lives in a jar not shipped to the cluster; key class relocated by a shading plugin so the runtime name differs from the serialized name; Avro/Protobuf-generated key class missing from the fat jar; mismatched dependency versions where the class package changed.","solutions":["Include the key class (and all its transitive dependencies) in the user-code jar submitted with the job.","If using shading, verify the key class's runtime name matches what was serialized (keep the class unshaded or remap consistently).","Rebuild and resubmit the fat jar so the TaskManager classloader can resolve the key type.","Confirm the key class is public and loadable by the user-code classloader."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Verify the key class is resolvable on the runtime classpath before submitting\nString keyName = keyClass.getName();\ntry {\n    Class.forName(keyName, true, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Key class \" + keyName\n        + \" is not on the runtime classpath; ship it in the user-code jar\", e);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Include key classes (and transitive deps) in the submitted user-code jar.","Keep shading consistent so runtime names match serialized names.","Verify generated key classes (Avro/Protobuf) are packaged.","Match dependency versions across build and cluster."],"tags":["hadoop","mapreduce","serialization","classloader","key-class"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}