apache/hadoop · error · IOException

Byte-per-checksum not matched: bpc={} but bytesPerCRC={}

Error message

Byte-per-checksum not matched: bpc={} but bytesPerCRC={}

What it means

While folding per-block checksums into a striped block-group checksum, setOrVerifyChecksumProperties found that internal block N's byte-per-checksum (bpc) differs from block 0's. A group-level checksum is only defined when every internal block of the EC group has identical checksum geometry, so the mismatch aborts the computation.

Source

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

        DataChecksum checksum = checksumRecon.getChecksum();
        long crcPerBlock = checksum.getChecksumSize() <= 0 ? 0
            : checksumRecon.getChecksumDataLen() / checksum.getChecksumSize();
        setOrVerifyChecksumProperties(errBlkIndex,
            checksum.getBytesPerChecksum(), crcPerBlock,
            checksum.getChecksumType());
        LOG.debug("Recalculated checksum for the block index:{}, checksum={}",
            errBlkIndex, checksumRecon.getDigestObject());
      }
    }

    private void setOrVerifyChecksumProperties(int blockIdx, int bpc,
        final long cpb, DataChecksum.Type ct) throws IOException {
      //read byte-per-checksum
      if (blockIdx == 0) { //first block
        setBytesPerCRC(bpc);
      } else if (bpc != getBytesPerCRC()) {
        throw new IOException("Byte-per-checksum not matched: bpc=" + bpc
            + " but bytesPerCRC=" + getBytesPerCRC());
      }

      //read crc-per-block
      if (blockIdx == 0) {
        setCrcPerBlock(cpb);
      }

      if (blockIdx == 0) { // first block
        setCrcType(ct);
      } else if (getCrcType() != DataChecksum.Type.MIXED &&
          getCrcType() != ct) {
        BlockChecksumType groupChecksumType =
            getBlockChecksumOptions().getBlockChecksumType();
        if (groupChecksumType == BlockChecksumType.COMPOSITE_CRC) {
          throw new IOException(String.format(
              "BlockChecksumType COMPOSITE_CRC doesn't support MIXED "
              + "underlying types; previous block was %s, next block is %s",

View on GitHub (pinned to 2add963021)

Solutions

1. Fall back to MD5CRC file checksum for the affected file — it tolerates MIXED checksum properties
2. Set one uniform dfs.bytes-per-checksum on all nodes and keep it stable going forward
3. Rewrite/migrate affected striped files (distcp) after fixing config so new copies are internally consistent

Example fix

# before (fails on mixed-geometry EC file)
hdfs dfs -checksum /ec/mixed-file  # client requests COMPOSITE_CRC

# after
# force MD5CRC in the client until the file is rewritten,
# e.g. -Ddfs.client.files.checksum-type=MD5CRC on checksum-capable tooling

// Client-side: inspect per-block checksum info before asking for composite
for (ExtendedBlock ib : group.getBlocks()) {
  if (first == null) first = bpcOf(ib);
  else if (bpcOf(ib) != first) { useComposite = false; break; }
}

try {
  cs = fs.getFileChecksum(path, COMPOSITE_CRC_OPTS);
} catch (IOException e) {
  if (e.getMessage().contains("Byte-per-checksum not matched")) {
    cs = fs.getFileChecksum(path, MD5CRC_OPTS); // MIXED is fine for MD5
  } else { throw e; }
}

When it happens

Trigger: Internal blocks of one EC block group written under different dfs.bytes-per-checksum values — config changed between writes/appends of the same striped file, or heterogeneous DataNode configurations at write time.

Common situations: Cluster-wide io.bytes.per.checksum changed mid-life of a file; nodes provisioned with divergent hdfs-site.xml; files appended after a config change.

Related errors

• BlockChecksumType COMPOSITE_CRC doesn't support MIXED underl
• Invalid values: dfs.bytes-per-checksum (={}) must divide cel
• Fail to get block checksum for {}
• FileSystem ${item.fs.getUri()} does not support Erasure Codi
• Could not create DataChecksum from the byte array of length

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