apache/hadoop · error · IllegalArgumentException

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

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

• Cannot parse string
• Number out of range: threshold =
• args =
• Failed to read node list from file
• Illegal option

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

Appendix: 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)