apache/hadoop · error · IllegalArgumentException

Block size must be greater than 0

Error message

Block size must be greater than 0

What it means

Options.CreateOpts.BlockSize (used via FileSystem.create(path, CreateOpts.blockSize(bs), ...) and friends) validates in its constructor that the block size is positive; bs <= 0 throws IllegalArgumentException immediately at option construction, before any filesystem call.

Source

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

    }
    public static Progress progress(Progressable prog) {
      return new Progress(prog);
    }
    public static Perms perms(FsPermission perm) {
      return new Perms(perm);
    }
    public static CreateParent createParent() {
      return new CreateParent(true);
    }
    public static CreateParent donotCreateParent() {
      return new CreateParent(false);
    }
    
    public static class BlockSize extends CreateOpts {
      private final long blockSize;
      protected BlockSize(long bs) {
        if (bs <= 0) {
          throw new IllegalArgumentException(
                        "Block size must be greater than 0");
        }
        blockSize = bs; 
      }
      public long getValue() { return blockSize; }
    }
    
    public static class ReplicationFactor extends CreateOpts {
      private final short replication;
      protected ReplicationFactor(short rf) { 
        if (rf <= 0) {
          throw new IllegalArgumentException(
                      "Replication must be greater than 0");
        }
        replication = rf;
      }
      public short getValue() { return replication; }
    }

View on GitHub (pinned to 2add963021)

Solutions

1. Fix the config source so the resolved block size is positive (check the actual key and its default)
2. Validate/compute bs > 0 before calling create; use the FileSystem default when unspecified
3. Never pass -1 sentinels into CreateOpts — omit the option to get the FS default

Example fix

// before
fs.create(out, CreateOpts.blockSize(conf.getLong("my.block.size", 0)));
// after
long bs = conf.getLongBytes("my.block.size", fs.getDefaultBlockSize(out));
fs.create(out, CreateOpts.blockSize(bs));

long bs = conf.getLongBytes("my.block.size", fs.getDefaultBlockSize(out));
if (bs <= 0) throw new IllegalArgumentException("block size must be > 0");
fs.create(out, CreateOpts.blockSize(bs));

When it happens

Trigger: CreateOpts.blockSize(n)/new CreateOpts.BlockSize(n) with n <= 0 — commonly a config lookup that defaulted to 0, a -1 'unspecified' sentinel leaking into the opts API, or an arithmetic/unit bug producing zero or negative sizes.

Common situations: Missing block-size config keys (fs.local.block.size / dfs.block.size) defaulting wrongly to 0, int overflow when computing sizes, code paths forwarding user input unvalidated.

Related errors

• Replication must be greater than 0
• Buffer size must be greater than 0
• Bytes per checksum 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/baa35a2fbe6c1f00. Report an issue: GitHub.