{"record":{"id":"a39c0a1a3edd7660","repo":"apache/hadoop","slug":"checksum-mismatch-between-and","errorCode":null,"errorMessage":"Checksum mismatch between {} and {}.","messagePattern":"Checksum mismatch between (.+?) and (.+?)\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-tools/hadoop-distcp/src/main/java/org/apache/hadoop/tools/util/DistCpUtils.java","lineNumber":660,"sourceCode":"              .append(\"Their checksum algorithms may be incompatible\");\n          addSkipHint = true;\n        } else if (sourceFS.getFileStatus(source).getBlockSize() !=\n            targetFS.getFileStatus(target).getBlockSize()) {\n          errorMessage.append(\" Source and target differ in block-size.\\n\")\n              .append(\" Use -pb to preserve block-sizes during copy.\");\n          addSkipHint = true;\n        }\n        if (addSkipHint) {\n          errorMessage\n              .append(\" You can choose file-level checksum validation via \"\n                  + \"-Ddfs.checksum.combine.mode=COMPOSITE_CRC when block-sizes\"\n                  + \" or filesystems are different.\")\n              .append(\" Or you can skip checksum-checks altogether \"\n                  + \" with -skipcrccheck.\\n\")\n              .append(\" (NOTE: By skipping checksums, one runs the risk of \" +\n                  \"masking data-corruption during file-transfer.)\\n\");\n        }\n        throw new IOException(errorMessage.toString());\n      }\n    }\n  }\n\n  /*\n   * Return the Path for a given chunk.\n   * Used when splitting large file into chunks to copy in parallel.\n   * @param targetFile path to target file\n   * @param srcFileStatus source file status in copy listing\n   * @return path to the chunk specified by the parameters to store\n   * in target cluster temporarily\n   */\n  public static Path getSplitChunkPath(Path targetFile,\n      CopyListingFileStatus srcFileStatus) {\n    return new Path(targetFile.toString()\n        + \".____distcpSplit____\" + srcFileStatus.getChunkOffset()\n        + \".\" + srcFileStatus.getChunkLength());\n  }","sourceCodeStart":642,"sourceCodeEnd":678,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-tools/hadoop-distcp/src/main/java/org/apache/hadoop/tools/util/DistCpUtils.java#L642-L678","documentation":"After a copy with lengths matching, DistCpUtils compares source and target checksums; on mismatch it throws an IOException built around CHECKSUM_MISMATCH_ERROR_MSG naming both files, plus remediation hints: file-level checksum validation via -Ddfs.checksum.combine.mode=COMPOSITE_CRC when block sizes or filesystems differ, or -skipcrccheck to skip validation. Since lengths already matched, this is either genuinely different bytes or an incomparable per-block checksum comparison.","triggerScenarios":"Source and target use different checksum types because block sizes or filesystem implementations differ (HDFS vs S3A, different dfs.block.size); actual corruption during transfer; the source file modified during the copy; clusters defaulting to different CRC algorithms.","commonSituations":"Cross-cluster or HDFS-to-object-store distcp where per-block CRCs are not comparable; migrations between HDFS versions with different checksum defaults; rare bit-rot during transfer.","solutions":["Make checksums comparable at file level: -Ddfs.checksum.combine.mode=COMPOSITE_CRC","If the integrity trade-off is acceptable, disable verification with -skipcrccheck (the message warns this can mask corruption)","If real corruption is suspected, verify the source with 'hdfs fsck <file> -files -blocks' and recopy","Align dfs.block.size between source and target so checksums compare equal"],"exampleFix":"# before: per-block CRCs incomparable across filesystems -> Checksum mismatch\nhadoop distcp -update hdfs://nnA/src hdfs://nnB/dst\n\n# after (pick one)\nhadoop distcp -update -Ddfs.checksum.combine.mode=COMPOSITE_CRC hdfs://nnA/src hdfs://nnB/dst\nhadoop distcp -update -skipcrccheck hdfs://nnA/src hdfs://nnB/dst","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"catch (IOException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"Checksum mismatch\")) {\n    // rerun with -Ddfs.checksum.combine.mode=COMPOSITE_CRC, or -skipcrccheck if risk accepted\n  }\n}","preventionTips":["Standardize on COMPOSITE_CRC when copying across filesystems or block sizes","Align dfs.block.size on source and target clusters","Reserve -skipcrccheck for cases where integrity risk is understood","Run hdfs fsck on sources when mismatches repeat on the same files"],"tags":["distcp","hadoop","checksum","verification","data-integrity"],"backgroundTag":"checksum-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}