apache/hadoop · error · IllegalArgumentException

args = {args}

Error message

args = {args}

What it means

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).

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/balancer/Balancer.java:1202

                  + Arrays.toString(args));
              long hotBlockTimeInterval = Long.parseLong(args[i]);
              LOG.info("Using a hotBlockTimeInterval of "
                  + hotBlockTimeInterval);
              b.setHotBlockTimeInterval(hotBlockTimeInterval);
            } else if ("-sortTopNodes".equalsIgnoreCase(args[i])) {
              b.setSortTopNodes(true);
              LOG.info("Balancer will sort nodes by" +
                  " capacity usage percentage to prioritize top used nodes");
            } else if ("-limitOverUtilizedNum".equalsIgnoreCase(args[i])) {
              Preconditions.checkArgument(++i < args.length,
                  "limitOverUtilizedNum value is missing: args = " + Arrays.toString(args));
              int limitNum = Integer.parseInt(args[i]);
              Preconditions.checkArgument(limitNum >= 0,
                  "limitOverUtilizedNum must be non-negative");
              LOG.info("Using a limitOverUtilizedNum of {}", limitNum);
              b.setLimitOverUtilizedNum(limitNum);
            } else {
              throw new IllegalArgumentException("args = "
                  + Arrays.toString(args));
            }
          }
          Preconditions.checkArgument(excludedNodes == null || includedNodes == null,
              "-exclude and -include options cannot be specified together.");
          Preconditions.checkArgument(excludedSourceNodes == null || sourceNodes == null,
              "-excludeSource and -source options cannot be specified together.");
          Preconditions.checkArgument(excludedTargetNodes == null || targetNodes == null,
              "-excludeTarget and -target options cannot be specified together.");
        } catch(RuntimeException e) {
          printUsage(System.err);
          throw e;
        }
      }
      return b.build();
    }

    private static int processHostList(String[] args, int i, String type,

View on GitHub (pinned to 2add963021)

Solutions

1. Run 'hdfs balancer -help' and correct the option name to exactly one of the documented flags
2. Check for stray/unquoted tokens in the script that invokes the balancer
3. Confirm the options you use exist in your deployed Hadoop version (options like -source/-target/-excludeSource were added in later releases)

Example fix

# before
hdfs balancer -threshhold 10

# after
hdfs balancer -threshold 10

static final Set<String> KNOWN = Set.of("-threshold", "-policy", "-include", "-exclude", "-source", "-excludeSource",
    "-target", "-excludeTarget", "-blockpools", "-idleiterations", "-runDuringUpgrade", "-sortTopNodes", "-limitOverUtilizedNum", "-f");
static boolean argsKnown(String[] args) {
  for (String a : args) if (a.startsWith("-") && !KNOWN.contains(a.toLowerCase())) return false;
  return true;
}

catch (IllegalArgumentException e) { Balancer.printUsage(System.err); System.exit(-1); } // the tool already prints usage before rethrowing

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Number out of range: threshold = {threshold}
• Cannot parse string "{s}"
• Illegal option {}
• Not enough arguments: expected {} but got {}
• Too many arguments: expected {} but got {}

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