{"record":{"id":"5251af3c382ccc33","repo":"apache/hadoop","slug":"unknown-checksumcombinemode","errorCode":null,"errorMessage":"Unknown ChecksumCombineMode: {}","messagePattern":"Unknown ChecksumCombineMode: (.+?)","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":116,"sourceCode":"                         LocatedBlocks blockLocations,\n                         ClientProtocol namenode,\n                         DFSClient client,\n                         ChecksumCombineMode combineMode) throws IOException {\n      this.src = src;\n      this.length = length;\n      this.blockLocations = blockLocations;\n      this.namenode = namenode;\n      this.client = client;\n      this.combineMode = combineMode;\n      switch (combineMode) {\n      case MD5MD5CRC:\n        this.blockChecksumType = BlockChecksumType.MD5CRC;\n        break;\n      case COMPOSITE_CRC:\n        this.blockChecksumType = BlockChecksumType.COMPOSITE_CRC;\n        break;\n      default:\n        throw new IOException(\"Unknown ChecksumCombineMode: \" + combineMode);\n      }\n\n      this.remaining = length;\n\n      if (blockLocations != null) {\n        if (src.contains(HdfsConstants.SEPARATOR_DOT_SNAPSHOT_DIR_SEPARATOR)) {\n          this.remaining = Math.min(length, blockLocations.getFileLength());\n        }\n        this.locatedBlocks = blockLocations.getLocatedBlocks();\n      }\n    }\n\n    String getSrc() {\n      return src;\n    }\n\n    long getLength() {\n      return length;","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/FileChecksumHelper.java#L98-L134","documentation":"FileChecksumComputer's constructor switches on the ChecksumCombineMode that controls how per-block checksums are combined into a file checksum (dfs.checksum.combine.mode). Only MD5MD5CRC and COMPOSITE_CRC exist; any other value throws this defensive IOException at construction. In practice the config parser (DfsClientConf) already falls back to MD5MD5CRC on bad strings, so reaching this branch requires an enum value the running jar does not know — i.e., a ChecksumCombineMode constant introduced by newer code but absent here.","triggerScenarios":"DFSClient.getFileChecksum() invoked while DfsClientConf holds a ChecksumCombineMode other than MD5MD5CRC/COMPOSITE_CRC; a new combine-mode enum value serialized or injected from newer components; unit tests constructing FileChecksumComputer with a mock/unknown mode.","commonSituations":"Mixed Hadoop jar versions on one client classpath (newer hdfs-client jar providing a new enum value, older helper code); custom forks adding combine modes; typo attempts in dfs.checksum.combine.mode are normally intercepted earlier by the valueOf fallback, so a genuine hit points at classpath skew.","solutions":["Set dfs.checksum.combine.mode to a known value: MD5MD5CRC (default) or COMPOSITE_CRC","Align all Hadoop jars (hadoop-hdfs-client, hadoop-common) to one version on the client classpath","If you run a fork that added a combine mode, make sure every node/client jar includes the new enum"],"exampleFix":"# before\ndfs.checksum.combine.mode=COMPOSITE_CRC_EXTRA   # unknown to this client jar\n\n# after\ndfs.checksum.combine.mode=COMPOSITE_CRC          # or MD5MD5CRC","handlingStrategy":"validation","validationCode":"// Fail fast at startup instead of at first checksum call:\nString mode = conf.get(\"dfs.checksum.combine.mode\", \"MD5MD5CRC\");\nif (!\"MD5MD5CRC\".equals(mode) && !\"COMPOSITE_CRC\".equals(mode)) {\n  throw new IllegalArgumentException(\"Invalid dfs.checksum.combine.mode: \" + mode);\n}","typeGuard":null,"tryCatchPattern":"try {\n  checksum = dfsClient.getFileChecksum(path);\n} catch (IOException e) {\n  if (e.getMessage().contains(\"Unknown ChecksumCombineMode\")) {\n    // classpath/version skew: log and retry with explicit default mode\n    conf.set(\"dfs.checksum.combine.mode\", \"MD5MD5CRC\");\n  } else { throw e; }\n}","preventionTips":["Validate dfs.checksum.combine.mode against {MD5MD5CRC, COMPOSITE_CRC} in config sanity checks at startup","Pin one Hadoop version across all client jars to avoid unknown enum values","Treat 'Unknown <Enum>' checksum errors as classpath skew and inspect jar provenance immediately"],"tags":["hdfs","checksum","configuration","enum","version-conflict"],"backgroundTag":"invalid-enum-config-value","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}