apache/hadoop · error · IOException

Unrecognized BlockChecksumType: %s

Error message

Unrecognized BlockChecksumType: %s

What it means

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.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/BlockChecksumHelper.java:308

      super(datanode, block, blockChecksumOptions);
    }

    @Override
    void compute() throws IOException {
      try {
        readHeader();

        BlockChecksumType type =
            getBlockChecksumOptions().getBlockChecksumType();
        switch (type) {
        case MD5CRC:
          computeMd5Crc();
          break;
        case COMPOSITE_CRC:
          computeCompositeCrc(getBlockChecksumOptions().getStripeLength());
          break;
        default:
          throw new IOException(String.format(
              "Unrecognized BlockChecksumType: %s", type));
        }
      } finally {
        IOUtils.closeStream(getChecksumIn());
        IOUtils.closeStream(getMetadataIn());
      }
    }

    private void computeMd5Crc() throws IOException {
      MD5Hash md5out;
      if (isPartialBlk() && getCrcPerBlock() > 0) {
        md5out = checksumPartialBlock();
      } else {
        md5out = checksumWholeBlock();
      }
      setOutBytes(md5out.getDigest());

      LOG.debug("block={}, bytesPerCRC={}, crcPerBlock={}, md5out={}",

View on GitHub (pinned to 2add963021)

Solutions

1. Align client, NameNode, and DataNode versions (finish the rolling upgrade) so all sides know the same BlockChecksumType values
2. If you control the request, retry with BlockChecksumType.MD5CRC, which every release supports
3. Verify the classpath has a single consistent hadoop-hdfs-client version (no stale jars)

Example fix

// before
BlockChecksumOptions opts =
    new BlockChecksumOptions(newTypeFromNewerBranch, cellSize);
client.getBlockChecksum(block, opts);

// after
if (newTypeFromNewerBranch != BlockChecksumType.MD5CRC
    && newTypeFromNewerBranch != BlockChecksumType.COMPOSITE_CRC) {
  newTypeFromNewerBranch = BlockChecksumType.MD5CRC; // safe on all DNs
}
BlockChecksumOptions opts =
    new BlockChecksumOptions(newTypeFromNewerBranch, cellSize);

BlockChecksumType t = opts.getBlockChecksumType();
if (t != BlockChecksumType.MD5CRC && t != BlockChecksumType.COMPOSITE_CRC) {
  throw new IllegalArgumentException("Unsupported BlockChecksumType: " + t);
}

static boolean isKnownBlockChecksumType(BlockChecksumType t) {
  return t == BlockChecksumType.MD5CRC
      || t == BlockChecksumType.COMPOSITE_CRC;
}

try {
  checksum = client.getBlockChecksum(block, opts);
} catch (IOException e) {
  if (e.getMessage().contains("Unrecognized BlockChecksumType")) {
    // version skew: fall back to the universally supported type
    checksum = client.getBlockChecksum(block,
        new BlockChecksumOptions(BlockChecksumType.MD5CRC, 0));
  } else {
    throw e;
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unknown BlockChecksumType: " + groupChecksumType
• Unexpected blockChecksumType '%s', expecting COMPOSITE_CRC
• {this}: invalid slot index {slotIdx}
• The value %d does not map to a valid checksum Type
• Version Mismatch (Expected: {}, Received: {} )

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/faa5c77db6c81c92. Report an issue: GitHub.