apache/hadoop · error · ChecksumException

Checksum file not a length multiple of checksum size in {} a

Error message

Checksum file not a length multiple of checksum size in {} at {} checksumpos: {} sumLenread: {}

What it means

LocalFileSystem is ChecksumFileSystem over RawLocalFileSystem: it keeps a sibling .<name>.crc file with an 8-byte header (version + bytesPerChecksum, default 512) followed by 4-byte CRC32 records (CHECKSUM_SIZE=4). During reads it loads checksum records; if the number of bytes read from the .crc is not a multiple of 4 it throws ChecksumException "Checksum file not a length multiple of checksum size...". The .crc file itself is malformed - typically truncated or partially copied - rather than the data being wrong.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/ChecksumFileSystem.java:298

        byte[] checksum) throws IOException {

      boolean eof = false;
      if (needChecksum()) {
        assert checksum != null; // we have a checksum buffer
        assert checksum.length % CHECKSUM_SIZE == 0; // it is sane length
        assert len >= bytesPerSum; // we must read at least one chunk

        final int checksumsToRead = Math.min(
          len/bytesPerSum, // number of checksums based on len to read
          checksum.length / CHECKSUM_SIZE); // size of checksum buffer
        long checksumPos = getChecksumFilePos(pos);
        if(checksumPos != sums.getPos()) {
          sums.seek(checksumPos);
        }

        int sumLenRead = sums.read(checksum, 0, CHECKSUM_SIZE * checksumsToRead);
        if (sumLenRead >= 0 && sumLenRead % CHECKSUM_SIZE != 0) {
          throw new ChecksumException(
            "Checksum file not a length multiple of checksum size " +
            "in " + file + " at " + pos + " checksumpos: " + checksumPos +
            " sumLenread: " + sumLenRead,
            pos);
        }
        if (sumLenRead <= 0) { // we're at the end of the file
          eof = true;
        } else {
          // Adjust amount of data to read based on how many checksum chunks we read
          len = Math.min(len, bytesPerSum * (sumLenRead / CHECKSUM_SIZE));
        }
      }
      if(pos != datas.getPos()) {
        datas.seek(pos);
      }
      int nread = readFully(datas, buf, offset, len);
      if (eof && nread > 0) {
        throw new ChecksumException("Checksum error: "+file+" at "+pos, pos);

View on GitHub (pinned to 2add963021)

Solutions

Delete or rename the matching .<name>.crc file - LocalFileSystem treats a missing crc as "no checksums" and reads proceed (integrity is then unchecked).
Better: re-copy both the data file and its .crc from the source so checksum coverage is restored.
If you must read immediately, bypass verification with fs.setVerifyChecksum(false) (or `hadoop fs -cat -ignoreCrc`), or configure fs.file.impl to RawLocalFileSystem.
After any bypass, independently verify data integrity (e.g. compare MD5 against the source) since corruption detection is gone.

Example fix

// before: read fails mid-file with ChecksumException

// after: drop the malformed checksum file, then re-read
Path crc = new Path(f.getParent(), "." + f.getName() + ".crc");
localFs.delete(crc, false);
try (FSDataInputStream in = localFs.open(f)) {
  in.readFully(buf);
}

Defensive patterns

Strategy: fallback

Validate before calling

// pre-flight: a .crc whose body is not 4-byte aligned (after the 8-byte header) will fail mid-read
Path crc = new Path(f.getParent(), "." + f.getName() + ".crc");
if (localFs.exists(crc)) {
  long n = localFs.getFileStatus(crc).getLen();
  if ((n - 8) % 4 != 0) {
    localFs.delete(crc, false); // drop malformed crc; reads proceed without checksums
  }
}

Try / catch

try {
  localFs.verifyChecksum? 0 : 0; // no-op; see fallback below
} finally { }

Prevention

Copy staging directories with tools that preserve or safely skip hidden dotfiles (.name.crc)
Prefer a quick alignment check on (crcLength - 8) % 4 before long local reads
If checksums are not wanted, configure fs.file.impl=RawLocalFileSystem up front instead of failing mid-read

When it happens

Trigger: Reading through LocalFileSystem a file whose .<name>.crc was truncated by an interrupted cp/rsync/scp (hidden dotfiles get copied partially), a disk-full crash during local write, or a stale .crc left next to a regenerated data file. Note the constructor only ignores a missing/unreadable crc at open time; a crc whose header parses but whose body is misaligned fails here mid-read.

Common situations: Staging/spill directories copied between hosts include the hidden .crc files and one arrives truncated; a job writing locally was killed, leaving a half-written checksum file that later reads trip over.

Related errors

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