apache/hadoop · error · IllegalArgumentException

Number out of range: threshold = {threshold}

Error message

Number out of range: threshold = {threshold}

What it means

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.

Source

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

    static BalancerParameters parse(String[] args) {
      Set<String> excludedNodes = null;
      Set<String> includedNodes = null;
      Set<String> sourceNodes = null;
      Set<String> excludedSourceNodes = null;
      Set<String> targetNodes = null;
      Set<String> excludedTargetNodes = null;
      BalancerParameters.Builder b = new BalancerParameters.Builder();

      if (args != null) {
        try {
          for(int i = 0; i < args.length; i++) {
            if ("-threshold".equalsIgnoreCase(args[i])) {
              Preconditions.checkArgument(++i < args.length,
                "Threshold value is missing: args = " + Arrays.toString(args));
              try {
                double threshold = Double.parseDouble(args[i]);
                if (threshold < 1 || threshold > 100) {
                  throw new IllegalArgumentException(
                      "Number out of range: threshold = " + threshold);
                }
                LOG.info( "Using a threshold of " + threshold );
                b.setThreshold(threshold);
              } catch(IllegalArgumentException e) {
                System.err.println(
                    "Expecting a number in the range of [1.0, 100.0]: "
                    + args[i]);
                throw e;
              }
            } else if ("-policy".equalsIgnoreCase(args[i])) {
              Preconditions.checkArgument(++i < args.length,
                "Policy value is missing: args = " + Arrays.toString(args));
              try {
                b.setBalancingPolicy(BalancingPolicy.parse(args[i]));
              } catch(IllegalArgumentException e) {
                System.err.println("Illegal policy name: " + args[i]);
                throw e;

View on GitHub (pinned to 2add963021)

Solutions

1. Pass a percentage between 1.0 and 100.0 inclusive, e.g. 'hdfs balancer -threshold 10' for 10%
2. For very aggressive balancing use the minimum legal value 1 (1%), and for very lax balancing pick a larger value like 20
3. Run 'hdfs balancer -help' to confirm current option syntax

Example fix

# before
hdfs balancer -threshold 0.5

# after
hdfs balancer -threshold 1

static double checkThreshold(String[] args) {
  for (int i = 0; i < args.length - 1; i++) {
    if ("-threshold".equalsIgnoreCase(args[i])) {
      double t = Double.parseDouble(args[i + 1]);
      if (t < 1.0 || t > 100.0) throw new IllegalArgumentException("threshold must be in [1.0, 100.0]");
      return t;
    }
  }
  return 10.0; // default
}

static boolean isValidThreshold(String s) {
  try { double v = Double.parseDouble(s); return v >= 1.0 && v <= 100.0; }
  catch (NumberFormatException e) { return false; }
}

catch (IllegalArgumentException e) { System.err.println("threshold must be a percentage in [1.0, 100.0]"); printUsage(); System.exit(-1); }

When it happens

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

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

Related errors

• args = {args}
• 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/aebf04c1b23784f7. Report an issue: GitHub.