apache/hadoop · error · IllegalArgumentException

Bytes per checksum must be greater than 0

Error message

Bytes per checksum must be greater than 0

What it means

Options.CreateOpts.BytesPerChecksum validates that bytesPerChecksum (a short) used with FileSystem.create(path, CreateOpts.bytesPerChecksum(bpc), ...) is positive; bpc <= 0 throws IllegalArgumentException at construction.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/Options.java:116

    
    public static class BufferSize extends CreateOpts {
      private final int bufferSize;
      protected BufferSize(int bs) {
        if (bs <= 0) {
          throw new IllegalArgumentException(
                        "Buffer size must be greater than 0");
        }
        bufferSize = bs; 
      }
      public int getValue() { return bufferSize; }
    }

    /** This is not needed if ChecksumParam is specified. **/
    public static class BytesPerChecksum extends CreateOpts {
      private final int bytesPerChecksum;
      protected BytesPerChecksum(short bpc) { 
        if (bpc <= 0) {
          throw new IllegalArgumentException(
                        "Bytes per checksum must be greater than 0");
        }
        bytesPerChecksum = bpc; 
      }
      public int getValue() { return bytesPerChecksum; }
    }

    public static class ChecksumParam extends CreateOpts {
      private final ChecksumOpt checksumOpt;
      protected ChecksumParam(ChecksumOpt csumOpt) {
        checksumOpt = csumOpt;
      }
      public ChecksumOpt getValue() { return checksumOpt; }
    }
    
    public static class Perms extends CreateOpts {
      private final FsPermission permissions;
      protected Perms(FsPermission perm) { 

View on GitHub (pinned to 2add963021)

Solutions

1. Set bytesPerChecksum to a positive value (HDFS default is 512)
2. Omit the BytesPerChecksum option and supply a ChecksumOpt instead when unsure
3. Validate bpc > 0 before constructing the option

Example fix

// before
CreateOpts.bytesPerChecksum((short) 0)
// after
CreateOpts.bytesPerChecksum((short) 512)   // > 0, matching io.bytes.per.checksum default

short bpc = (short) conf.getInt("io.bytes.per.checksum", 512);
if (bpc <= 0) throw new IllegalArgumentException("bytes per checksum must be > 0");
fs.create(out, CreateOpts.bytesPerChecksum(bpc));

When it happens

Trigger: CreateOpts.bytesPerChecksum(n) with n <= 0 — e.g. io.bytes.per.checksum set to 0, or code forwarding a defaulted/zeroed value into the option.

Common situations: Checksum config disabled by setting 0, mixed old/new config files after upgrades, unvalidated computed values.

Related errors

• Block size must be greater than 0
• Replication must be greater than 0
• Buffer size must be greater than 0
• Path must be absolute: " + path
• Copy destination must be different from source for %s.

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