{"record":{"id":"aebf04c1b23784f7","repo":"apache/hadoop","slug":"number-out-of-range-threshold-threshold","errorCode":null,"errorMessage":"Number out of range: threshold = {threshold}","messagePattern":"Number out of range: threshold = (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/balancer/Balancer.java","lineNumber":1112,"sourceCode":"    static BalancerParameters parse(String[] args) {\n      Set<String> excludedNodes = null;\n      Set<String> includedNodes = null;\n      Set<String> sourceNodes = null;\n      Set<String> excludedSourceNodes = null;\n      Set<String> targetNodes = null;\n      Set<String> excludedTargetNodes = null;\n      BalancerParameters.Builder b = new BalancerParameters.Builder();\n\n      if (args != null) {\n        try {\n          for(int i = 0; i < args.length; i++) {\n            if (\"-threshold\".equalsIgnoreCase(args[i])) {\n              Preconditions.checkArgument(++i < args.length,\n                \"Threshold value is missing: args = \" + Arrays.toString(args));\n              try {\n                double threshold = Double.parseDouble(args[i]);\n                if (threshold < 1 || threshold > 100) {\n                  throw new IllegalArgumentException(\n                      \"Number out of range: threshold = \" + threshold);\n                }\n                LOG.info( \"Using a threshold of \" + threshold );\n                b.setThreshold(threshold);\n              } catch(IllegalArgumentException e) {\n                System.err.println(\n                    \"Expecting a number in the range of [1.0, 100.0]: \"\n                    + args[i]);\n                throw e;\n              }\n            } else if (\"-policy\".equalsIgnoreCase(args[i])) {\n              Preconditions.checkArgument(++i < args.length,\n                \"Policy value is missing: args = \" + Arrays.toString(args));\n              try {\n                b.setBalancingPolicy(BalancingPolicy.parse(args[i]));\n              } catch(IllegalArgumentException e) {\n                System.err.println(\"Illegal policy name: \" + args[i]);\n                throw e;","sourceCodeStart":1094,"sourceCodeEnd":1130,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/balancer/Balancer.java#L1094-L1130","documentation":"Thrown while parsing the '-threshold' CLI option of 'hdfs balancer'. The threshold is a percentage of datanode disk capacity used to define over/under-utilized nodes, and the code only accepts values in the closed range [1.0, 100.0]. Values outside the range (or a follow-up token that parses as a number but is out of range) raise IllegalArgumentException after printing a hint to stderr; usage is printed and the tool exits.","triggerScenarios":"hdfs balancer -threshold 0, -threshold 0.5 (assuming a fraction), -threshold 150, or a typo like -threshold 1O (that fails parsing earlier with NumberFormatException). The range check 'threshold < 1 || threshold > 100' produces this exact message.","commonSituations":"Operators used to tools that take a 0-1 fraction; attempts to 'balance everything' with 100+; attempts to make the balancer ultra-sensitive with a sub-1 percent threshold.","solutions":["Pass a percentage between 1.0 and 100.0 inclusive, e.g. 'hdfs balancer -threshold 10' for 10%","For very aggressive balancing use the minimum legal value 1 (1%), and for very lax balancing pick a larger value like 20","Run 'hdfs balancer -help' to confirm current option syntax"],"exampleFix":"# before\nhdfs balancer -threshold 0.5\n\n# after\nhdfs balancer -threshold 1","handlingStrategy":"validation","validationCode":"static double checkThreshold(String[] args) {\n  for (int i = 0; i < args.length - 1; i++) {\n    if (\"-threshold\".equalsIgnoreCase(args[i])) {\n      double t = Double.parseDouble(args[i + 1]);\n      if (t < 1.0 || t > 100.0) throw new IllegalArgumentException(\"threshold must be in [1.0, 100.0]\");\n      return t;\n    }\n  }\n  return 10.0; // default\n}","typeGuard":"static boolean isValidThreshold(String s) {\n  try { double v = Double.parseDouble(s); return v >= 1.0 && v <= 100.0; }\n  catch (NumberFormatException e) { return false; }\n}","tryCatchPattern":"catch (IllegalArgumentException e) { System.err.println(\"threshold must be a percentage in [1.0, 100.0]\"); printUsage(); System.exit(-1); }","preventionTips":["Treat -threshold as a whole-percent value (10 = 10%), never a fraction","Validate CLI args in wrapper scripts before launching the balancer"],"tags":["hdfs","balancer","cli","argument-validation","range-check"],"backgroundTag":"argument-out-of-range","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}