apache/hadoop · error · IllegalArgumentException

Replication must be greater than 0

Error message

Replication must be greater than 0

What it means

Options.CreateOpts.ReplicationFactor validates that the replication factor passed to FileSystem.create(path, CreateOpts.replication(rf), ...) is a positive short; rf <= 0 throws IllegalArgumentException at option construction time.

Source

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

    }
    
    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; }
    }
    
    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; }
    }

View on GitHub (pinned to 2add963021)

Solutions

1. Fix the replication config value (dfs.replication) to a positive integer
2. Default to fs.getDefaultReplication(path) when the caller has no explicit value
3. Validate replication > 0 before building CreateOpts

Example fix

// before
CreateOpts.replication((short) conf.getInt("my.repl", -1))
// after
short repl = (short) Math.max(1, conf.getInt("my.repl", fs.getDefaultReplication(out)));
CreateOpts.replication(repl)

short repl = (short) Math.max(1,
    conf.getInt("my.repl", fs.getDefaultReplication(out)));
if (repl <= 0) throw new IllegalArgumentException("replication must be > 0");
fs.create(out, CreateOpts.replication(repl));

When it happens

Trigger: CreateOpts.replication(rf) with rf <= 0 — e.g. dfs.replication configured to 0 or negative, a cast from a defaulted int config, or a computed replication of 0 for tiny/test clusters.

Common situations: Misconfigured replication in site XML, property typos falling back to 0, code paths propagating user input unchecked.

Related errors

• Block size 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/dc539fd00a07f5eb. Report an issue: GitHub.