{"record":{"id":"0576f5604bd8a7c7","repo":"apache/hadoop","slug":"replication-must-be-1","errorCode":null,"errorMessage":"replication must be >= 1","messagePattern":"replication must be >= 1","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/SetReplication.java","lineNumber":70,"sourceCode":"  protected short newRep = 0;\n  protected List<PathData> waitList = new LinkedList<PathData>();\n  protected boolean waitOpt = false;\n  \n  @Override\n  protected void processOptions(LinkedList<String> args) throws IOException {\n    CommandFormat cf = new CommandFormat(2, Integer.MAX_VALUE, \"R\", \"w\");\n    cf.parse(args);\n    waitOpt = cf.getOpt(\"w\");\n    setRecursive(true);\n    \n    try {\n      newRep = Short.parseShort(args.removeFirst());\n    } catch (NumberFormatException nfe) {\n      displayWarning(\"Illegal replication, a positive integer expected\");\n      throw nfe;\n    }\n    if (newRep < 1) {\n      throw new IllegalArgumentException(\"replication must be >= 1\");\n    }\n  }\n\n  @Override\n  protected void processArguments(LinkedList<PathData> args)\n  throws IOException {\n    super.processArguments(args);\n    if (waitOpt) waitForReplication();\n  }\n\n  @Override\n  protected void processPath(PathData item) throws IOException {\n    if (item.stat.isSymlink()) {\n      throw new PathIOException(item.toString(), \"Symlinks unsupported\");\n    }\n    \n    if (item.stat.isFile()) {\n      // Do the checking if the file is erasure coded since","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/SetReplication.java#L52-L88","documentation":"SetReplication.processOptions (SetReplication.java:70) parses the first remaining argument as a short and throws IllegalArgumentException('replication must be >= 1') when the parsed value is below 1. A separate NumberFormatException path handles non-numeric input ('Illegal replication, a positive integer expected'), so this specific throw means the value WAS a valid short integer but was 0 or negative.","triggerScenarios":"'hadoop fs -setrep 0 /path', 'hadoop fs -setrep -3 /path' (any integer < 1 as the first positional argument). Note: '-3' may be consumed as an option-looking token by CommandFormat first, but explicit 0 reliably reaches the check.","commonSituations":"Scripts computing replication from a variable that can be 0/unset; attempts to 'disable' replication by setting 0 (erasure-coded or archive intent); confusing replication factor with block size or memory settings in automation.","solutions":["Use a replication factor of at least 1: 'hadoop fs -setrep 3 /path'","Default the variable in scripts: REP=${REP:-3} before invoking -setrep","If the goal was cheaper storage, use erasure coding (HDFS EC policies) instead of replication 0 — EC files are skipped by setrep, not assigned 0"],"exampleFix":"# before\nhadoop fs -setrep 0 /data/archive\n# setrep: replication must be >= 1\n\n# after\nhadoop fs -setrep 1 /data/archive","handlingStrategy":"validation","validationCode":"short rep = Short.parseShort(repArg);\nif (rep < 1) throw new IllegalArgumentException(\"replication must be >= 1\");\n// guard in scripts: REP=${REP:-3}; (( REP >= 1 )) || exit 1","typeGuard":null,"tryCatchPattern":"catch (IllegalArgumentException e) when 'replication must be >= 1' -> clamp to a valid factor (>=1) or abort with a clear config error","preventionTips":["Default replication variables in scripts","Validate numeric args before invoking -setrep","Use EC policies, not replication 0, for cold data"],"tags":["setrep","replication-factor","invalid-argument","argument-validation"],"backgroundTag":"invalid-replication-factor","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}