{"record":{"id":"3e3ff634ea62cb13","repo":"apache/hadoop","slug":"byte-per-checksum-not-matched-bpc-but-bytesper","errorCode":null,"errorMessage":"Byte-per-checksum not matched: bpc={} but bytesPerCRC={}","messagePattern":"Byte-per-checksum not matched: bpc=(.+?) but bytesPerCRC=(.+?)","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":736,"sourceCode":"\n        DataChecksum checksum = checksumRecon.getChecksum();\n        long crcPerBlock = checksum.getChecksumSize() <= 0 ? 0\n            : checksumRecon.getChecksumDataLen() / checksum.getChecksumSize();\n        setOrVerifyChecksumProperties(errBlkIndex,\n            checksum.getBytesPerChecksum(), crcPerBlock,\n            checksum.getChecksumType());\n        LOG.debug(\"Recalculated checksum for the block index:{}, checksum={}\",\n            errBlkIndex, checksumRecon.getDigestObject());\n      }\n    }\n\n    private void setOrVerifyChecksumProperties(int blockIdx, int bpc,\n        final long cpb, DataChecksum.Type ct) throws IOException {\n      //read byte-per-checksum\n      if (blockIdx == 0) { //first block\n        setBytesPerCRC(bpc);\n      } else if (bpc != getBytesPerCRC()) {\n        throw new IOException(\"Byte-per-checksum not matched: bpc=\" + bpc\n            + \" but bytesPerCRC=\" + getBytesPerCRC());\n      }\n\n      //read crc-per-block\n      if (blockIdx == 0) {\n        setCrcPerBlock(cpb);\n      }\n\n      if (blockIdx == 0) { // first block\n        setCrcType(ct);\n      } else if (getCrcType() != DataChecksum.Type.MIXED &&\n          getCrcType() != ct) {\n        BlockChecksumType groupChecksumType =\n            getBlockChecksumOptions().getBlockChecksumType();\n        if (groupChecksumType == BlockChecksumType.COMPOSITE_CRC) {\n          throw new IOException(String.format(\n              \"BlockChecksumType COMPOSITE_CRC doesn't support MIXED \"\n              + \"underlying types; previous block was %s, next block is %s\",","sourceCodeStart":718,"sourceCodeEnd":754,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/BlockChecksumHelper.java#L718-L754","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fall back to MD5CRC file checksum for the affected file — it tolerates MIXED checksum properties","Set one uniform dfs.bytes-per-checksum on all nodes and keep it stable going forward","Rewrite/migrate affected striped files (distcp) after fixing config so new copies are internally consistent"],"exampleFix":"# before (fails on mixed-geometry EC file)\nhdfs dfs -checksum /ec/mixed-file  # client requests COMPOSITE_CRC\n\n# after\n# force MD5CRC in the client until the file is rewritten,\n# e.g. -Ddfs.client.files.checksum-type=MD5CRC on checksum-capable tooling","handlingStrategy":"fallback","validationCode":"// Client-side: inspect per-block checksum info before asking for composite\nfor (ExtendedBlock ib : group.getBlocks()) {\n  if (first == null) first = bpcOf(ib);\n  else if (bpcOf(ib) != first) { useComposite = false; break; }\n}","typeGuard":null,"tryCatchPattern":"try {\n  cs = fs.getFileChecksum(path, COMPOSITE_CRC_OPTS);\n} catch (IOException e) {\n  if (e.getMessage().contains(\"Byte-per-checksum not matched\")) {\n    cs = fs.getFileChecksum(path, MD5CRC_OPTS); // MIXED is fine for MD5\n  } else { throw e; }\n}","preventionTips":["Set dfs.bytes-per-checksum once at cluster setup and never change it","When a checksum-config change is unavoidable, rewrite existing files (distcp) so their internal blocks become consistent"],"tags":["hdfs","erasure-coding","checksum","configuration-mismatch"],"backgroundTag":"checksum-config-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}