{"record":{"id":"c49d1399b62d58eb","repo":"apache/hadoop","slug":"args-args","errorCode":null,"errorMessage":"args = {args}","messagePattern":"args = (.+?)","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":1202,"sourceCode":"                  + Arrays.toString(args));\n              long hotBlockTimeInterval = Long.parseLong(args[i]);\n              LOG.info(\"Using a hotBlockTimeInterval of \"\n                  + hotBlockTimeInterval);\n              b.setHotBlockTimeInterval(hotBlockTimeInterval);\n            } else if (\"-sortTopNodes\".equalsIgnoreCase(args[i])) {\n              b.setSortTopNodes(true);\n              LOG.info(\"Balancer will sort nodes by\" +\n                  \" capacity usage percentage to prioritize top used nodes\");\n            } else if (\"-limitOverUtilizedNum\".equalsIgnoreCase(args[i])) {\n              Preconditions.checkArgument(++i < args.length,\n                  \"limitOverUtilizedNum value is missing: args = \" + Arrays.toString(args));\n              int limitNum = Integer.parseInt(args[i]);\n              Preconditions.checkArgument(limitNum >= 0,\n                  \"limitOverUtilizedNum must be non-negative\");\n              LOG.info(\"Using a limitOverUtilizedNum of {}\", limitNum);\n              b.setLimitOverUtilizedNum(limitNum);\n            } else {\n              throw new IllegalArgumentException(\"args = \"\n                  + Arrays.toString(args));\n            }\n          }\n          Preconditions.checkArgument(excludedNodes == null || includedNodes == null,\n              \"-exclude and -include options cannot be specified together.\");\n          Preconditions.checkArgument(excludedSourceNodes == null || sourceNodes == null,\n              \"-excludeSource and -source options cannot be specified together.\");\n          Preconditions.checkArgument(excludedTargetNodes == null || targetNodes == null,\n              \"-excludeTarget and -target options cannot be specified together.\");\n        } catch(RuntimeException e) {\n          printUsage(System.err);\n          throw e;\n        }\n      }\n      return b.build();\n    }\n\n    private static int processHostList(String[] args, int i, String type,","sourceCodeStart":1184,"sourceCodeEnd":1220,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/balancer/Balancer.java#L1184-L1220","documentation":"The final else branch of Balancer.run(String[] args, ...) argument loop: any token that is not one of the recognized balancer options throws IllegalArgumentException('args = ' + Arrays.toString(args)) after printUsage. It fires for unknown option tokens and for stray positional tokens (a value whose flag is missing or misspelled gets interpreted as an option).","triggerScenarios":"A typo in an option (-threshhold), passing Mover/dfsadmin-style flags to the balancer, a stray value after a missing flag (e.g. 'hdfs balancer 10'), or shell quoting that splits an argument unexpectedly.","commonSituations":"Scripts written for a different Hadoop version whose balancer accepts different options; copy-pasted command lines from documentation for a newer/older branch; automation passing an empty string as a token.","solutions":["Run 'hdfs balancer -help' and correct the option name to exactly one of the documented flags","Check for stray/unquoted tokens in the script that invokes the balancer","Confirm the options you use exist in your deployed Hadoop version (options like -source/-target/-excludeSource were added in later releases)"],"exampleFix":"# before\nhdfs balancer -threshhold 10\n\n# after\nhdfs balancer -threshold 10","handlingStrategy":"validation","validationCode":"static final Set<String> KNOWN = Set.of(\"-threshold\", \"-policy\", \"-include\", \"-exclude\", \"-source\", \"-excludeSource\",\n    \"-target\", \"-excludeTarget\", \"-blockpools\", \"-idleiterations\", \"-runDuringUpgrade\", \"-sortTopNodes\", \"-limitOverUtilizedNum\", \"-f\");\nstatic boolean argsKnown(String[] args) {\n  for (String a : args) if (a.startsWith(\"-\") && !KNOWN.contains(a.toLowerCase())) return false;\n  return true;\n}","typeGuard":null,"tryCatchPattern":"catch (IllegalArgumentException e) { Balancer.printUsage(System.err); System.exit(-1); } // the tool already prints usage before rethrowing","preventionTips":["Pin balancer command lines in reviewed scripts; run 'hdfs balancer -help' after Hadoop upgrades","Fail fast on unknown tokens in wrappers (see argsKnown) instead of relying on the tool"],"tags":["hdfs","balancer","cli","argument-validation"],"backgroundTag":"unknown-cli-option","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}