{"record":{"id":"06c60821e57f156b","repo":"apache/hadoop","slug":"unknown-blockchecksumtype","errorCode":null,"errorMessage":"Unknown BlockChecksumType: {}","messagePattern":"Unknown BlockChecksumType: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/FileChecksumHelper.java","lineNumber":461,"sourceCode":"          blockChecksumForDebug = md5.toString();\n        }\n        break;\n      case COMPOSITE_CRC:\n        BlockChecksumType returnedType = PBHelperClient.convert(\n            checksumData.getBlockChecksumOptions().getBlockChecksumType());\n        if (returnedType != BlockChecksumType.COMPOSITE_CRC) {\n          throw new IOException(String.format(\n              \"Unexpected blockChecksumType '%s', expecting COMPOSITE_CRC\",\n              returnedType));\n        }\n        byte[] crcBytes = checksumData.getBlockChecksum().toByteArray();\n        if (LOG.isDebugEnabled()) {\n          blockChecksumForDebug = CrcUtil.toSingleCrcString(crcBytes);\n        }\n        getBlockChecksumBuf().write(crcBytes);\n        break;\n      default:\n        throw new IOException(\n            \"Unknown BlockChecksumType: \" + getBlockChecksumType());\n      }\n      return blockChecksumForDebug;\n    }\n  }\n\n  /**\n   * Replicated file checksum computer.\n   */\n  static class ReplicatedFileChecksumComputer extends FileChecksumComputer {\n    private int blockIdx;\n\n    ReplicatedFileChecksumComputer(String src, long length,\n                                   LocatedBlocks blockLocations,\n                                   ClientProtocol namenode,\n                                   DFSClient client,\n                                   ChecksumCombineMode combineMode)\n        throws IOException {","sourceCodeStart":443,"sourceCodeEnd":479,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/FileChecksumHelper.java#L443-L479","documentation":"The switch that dispatches on the requested BlockChecksumType (MD5CRC vs COMPOSITE_CRC) has no other cases, so any other value reaches the default and throws 'Unknown BlockChecksumType'. The public enum only defines those two constants, so through configuration this is unreachable; it fires only when getBlockChecksumType() returns something from a mismatched/newer enum class — i.e., mixed Hadoop jar versions on the classpath or forked code.","triggerScenarios":"FileChecksumComputer.blockChecksum() invoked when the BlockChecksumType instance was loaded from a different (newer or forked) jar than the switch code; reflective/test code injecting a foreign constant; shaded-plugin conflicts inside one JVM.","commonSituations":"Applications embedding multiple Hadoop versions (e.g., Spark bundling 3.x plus a user-supplied 3.3.x hdfs-client); fat jars that fail to shade org.apache.hadoop consistently; custom Hadoop forks adding a checksum type.","solutions":["Deduplicate Hadoop artifacts: print ChecksumCombineMode/BlockChecksumType .class.getProtectionDomain().getCodeSource() to find the rogue jar","Align every org.apache.hadoop dependency to one version via dependencyManagement or shading","Restart the JVM after fixing the classpath — stale enum classes from earlier loads can persist"],"exampleFix":"// before: unknown type slips through the switch\ncase COMPOSITE_CRC: ...\ndefault: throw new IOException(\"Unknown BlockChecksumType: \" + getBlockChecksumType());\n\n// after (build-time): single hadoop version\n// mvn dependency:tree -Dincludes=org.apache.hadoop  -> exactly one hdfs-client version\n<dependencyManagement>\n  <dependency>\n    <groupId>org.apache.hadoop</groupId>\n    <artifactId>hadoop-hdfs-client</artifactId>\n    <version>3.3.6</version>\n  </dependency>\n</dependencyManagement>","handlingStrategy":"validation","validationCode":"// Verify classpath coherence before checksum jobs:\nClass<?> a = BlockChecksumType.MD5CRC.getClass();\nClass<?> b = FileChecksumHelper.class; // same ProtectionDomain expected\nSystem.out.println(a.getProtectionDomain().getCodeSource());\nSystem.out.println(b.getProtectionDomain().getCodeSource()); // must match","typeGuard":null,"tryCatchPattern":"try {\n  checksum = client.getFileChecksum(path);\n} catch (IOException e) {\n  if (e.getMessage().contains(\"Unknown BlockChecksumType\")) {\n    throw new IllegalStateException(\"Conflicting Hadoop jars on classpath\", e);\n  }\n  throw e;\n}","preventionTips":["Enforce a single org.apache.hadoop version with dependencyManagement or a bill-of-materials","Smoke-test getFileChecksum() in CI for applications bundling Hadoop","When shading, relocate all org.apache.hadoop packages consistently or none"],"tags":["hdfs","checksum","classpath","enum","version-conflict"],"backgroundTag":"classpath-version-conflict","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}