apache/hadoop · error · PathIOException

Fail to get block checksum for {}

Error message

Fail to get block checksum for {}

What it means

The erasure-coded counterpart of the replicated block-checksum failure: StripedFileChecksumComputer iterates block groups, and if checksumBlockGroup() cannot obtain the group's checksum (reading data + parity chunks and reconstructing failed), it throws PathIOException with the file path and LocatedBlock. Because EC reconstructs from parity, this fires when reconstruction attempts inside the group also failed — e.g., more unavailable chunks than parity, or DataNode read errors on the chunks contacted.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/FileChecksumHelper.java:630

    }

    @Override
    void checksumBlocks() throws IOException {
      int tmpTimeout = getClient().getConf().getChecksumEcSocketTimeout() * 1 +
          getClient().getConf().getSocketTimeout();
      setTimeout(tmpTimeout);

      for (bgIdx = 0;
           bgIdx < getLocatedBlocks().size() && getRemaining() >= 0; bgIdx++) {
        if (isRefetchBlocks()) {  // refetch to get fresh tokens
          refetchBlocks();
        }

        LocatedBlock locatedBlock = getLocatedBlocks().get(bgIdx);
        LocatedStripedBlock blockGroup = (LocatedStripedBlock) locatedBlock;

        if (!checksumBlockGroup(blockGroup)) {
          throw new PathIOException(
              getSrc(), "Fail to get block checksum for " + locatedBlock);
        }
      }
    }


    private boolean checksumBlockGroup(
        LocatedStripedBlock blockGroup) throws IOException {
      ExtendedBlock block = blockGroup.getBlock();
      long requestedNumBytes = block.getNumBytes();
      if (getRemaining() < block.getNumBytes()) {
        requestedNumBytes = getRemaining();
      }
      setRemaining(getRemaining() - requestedNumBytes);

      StripedBlockInfo stripedBlockInfo = new StripedBlockInfo(block,
          blockGroup.getLocations(), blockGroup.getBlockTokens(),
          blockGroup.getBlockIndices(), ecPolicy);

View on GitHub (pinned to 2add963021)

Solutions

1. Check DataNode health (hdfs dfsadmin -report) and bring failed nodes back — EC tolerates up to parity-count failures
2. Run hdfs fsck /path -files -blocks -locations -replicaDetails to see damaged EC stripes
3. Retry when the cluster is stable; transient chunk-read failures are common during heavy load
4. If stripes exceed the failure threshold, restore data from source or re-distcp; also consider a lower-width EC policy for higher fault tolerance on critical data

// Before checksumming EC files, confirm enough DataNodes are live:
// parity tolerance = policy parity count; check with:
//   hdfs dfsadmin -report | grep -c Live
// and fsck the file: hdfs fsck /path -files -blocks -locations

try {
  return dfsClient.getFileChecksum(ecPath);
} catch (PathIOException e) {
  if (String.valueOf(e.getMessage()).contains("Fail to get block checksum")) {
    // striped reconstruction failed; wait for DataNode recovery, then retry
    scheduleRetryWithBackoff(ecPath);
  } else throw e;
}

When it happens

Trigger: getFileChecksum() on an erasure-coded (e.g., RS-6-3) file when a block group's chunks cannot all be read or reconstructed: DataNodes for data chunks and parity chunks down simultaneously, corrupted chunks, or read timeouts during the striped read.

Common situations: EC files with multiple DataNode failures at or beyond the parity limit; slow/degraded DataNodes causing striped-read failures; verifying checksums of EC datasets during cluster maintenance windows.

Related errors

• Unknown BlockChecksumType: " + groupChecksumType
• Byte-per-checksum not matched: bpc={} but bytesPerCRC={}
• {} has no enough internal blocks(current: {}), unable to sta
• Meta-data not found for {block}
• Checksum failed at {failedPos} for replica: {replica}

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