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.

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

• Buffer size must be greater than 0
• Bytes per checksum must be greater than 0
• Replication must be greater than 0
• Copy destination must be different from source for
• Illegal maxload factor

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

Appendix: 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)