{"record":{"id":"faa5c77db6c81c92","repo":"apache/hadoop","slug":"unrecognized-blockchecksumtype-s","errorCode":null,"errorMessage":"Unrecognized BlockChecksumType: %s","messagePattern":"Unrecognized BlockChecksumType: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/BlockChecksumHelper.java","lineNumber":308,"sourceCode":"      super(datanode, block, blockChecksumOptions);\n    }\n\n    @Override\n    void compute() throws IOException {\n      try {\n        readHeader();\n\n        BlockChecksumType type =\n            getBlockChecksumOptions().getBlockChecksumType();\n        switch (type) {\n        case MD5CRC:\n          computeMd5Crc();\n          break;\n        case COMPOSITE_CRC:\n          computeCompositeCrc(getBlockChecksumOptions().getStripeLength());\n          break;\n        default:\n          throw new IOException(String.format(\n              \"Unrecognized BlockChecksumType: %s\", type));\n        }\n      } finally {\n        IOUtils.closeStream(getChecksumIn());\n        IOUtils.closeStream(getMetadataIn());\n      }\n    }\n\n    private void computeMd5Crc() throws IOException {\n      MD5Hash md5out;\n      if (isPartialBlk() && getCrcPerBlock() > 0) {\n        md5out = checksumPartialBlock();\n      } else {\n        md5out = checksumWholeBlock();\n      }\n      setOutBytes(md5out.getDigest());\n\n      LOG.debug(\"block={}, bytesPerCRC={}, crcPerBlock={}, md5out={}\",","sourceCodeStart":290,"sourceCodeEnd":326,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/BlockChecksumHelper.java#L290-L326","documentation":"Thrown by the DataNode while computing a block-level checksum: the BlockChecksumType inside BlockChecksumOptions matched neither MD5CRC nor COMPOSITE_CRC, so the dispatch switch in BlockChecksumHelper fell through to its default arm. It means the checksum request carries an enum value this DataNode build cannot process.","triggerScenarios":"A client/NN sends OP_BLOCK_CHECKSUM whose protobuf BlockChecksumType ordinal is unknown to this DN (newer enum deserialized by older code via PBHelperClient.convert), or code constructs BlockChecksumOptions directly with an out-of-range enum value.","commonSituations":"Rolling-upgrade version skew (newer client asking an older DN), experimental branches that add a checksum type, mismatched/stray hadoop-hdfs-client jars on the classpath, corrupted DataTransferProtocol payload.","solutions":["Align client, NameNode, and DataNode versions (finish the rolling upgrade) so all sides know the same BlockChecksumType values","If you control the request, retry with BlockChecksumType.MD5CRC, which every release supports","Verify the classpath has a single consistent hadoop-hdfs-client version (no stale jars)"],"exampleFix":"// before\nBlockChecksumOptions opts =\n    new BlockChecksumOptions(newTypeFromNewerBranch, cellSize);\nclient.getBlockChecksum(block, opts);\n\n// after\nif (newTypeFromNewerBranch != BlockChecksumType.MD5CRC\n    && newTypeFromNewerBranch != BlockChecksumType.COMPOSITE_CRC) {\n  newTypeFromNewerBranch = BlockChecksumType.MD5CRC; // safe on all DNs\n}\nBlockChecksumOptions opts =\n    new BlockChecksumOptions(newTypeFromNewerBranch, cellSize);","handlingStrategy":"try-catch","validationCode":"BlockChecksumType t = opts.getBlockChecksumType();\nif (t != BlockChecksumType.MD5CRC && t != BlockChecksumType.COMPOSITE_CRC) {\n  throw new IllegalArgumentException(\"Unsupported BlockChecksumType: \" + t);\n}","typeGuard":"static boolean isKnownBlockChecksumType(BlockChecksumType t) {\n  return t == BlockChecksumType.MD5CRC\n      || t == BlockChecksumType.COMPOSITE_CRC;\n}","tryCatchPattern":"try {\n  checksum = client.getBlockChecksum(block, opts);\n} catch (IOException e) {\n  if (e.getMessage().contains(\"Unrecognized BlockChecksumType\")) {\n    // version skew: fall back to the universally supported type\n    checksum = client.getBlockChecksum(block,\n        new BlockChecksumOptions(BlockChecksumType.MD5CRC, 0));\n  } else {\n    throw e;\n  }\n}","preventionTips":["Keep client, NameNode, and DataNode releases aligned during and after rolling upgrades","Never construct BlockChecksumOptions from raw ordinal ints without validating the enum","Run a canary fileChecksum against every DN version before enabling new checksum types"],"tags":["hdfs","datanode","block-checksum","enum-switch","version-skew"],"backgroundTag":"unhandled-enum-value","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}