apache/hadoop · error · HadoopIllegalArgumentException

{key} = {v} <= 0

Error message

{key} = {v} <= 0

What it means

Balancer.getLong reads a long-typed balancer configuration key, logs its effective value, and throws HadoopIllegalArgumentException when the value is zero or negative. The balancer enforces positivity for its tuning knobs (timeouts, sizes, limits) because a non-positive value would make the run meaningless. The exception message names the exact key and offending value.

Source

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

  /* Check that this Balancer is compatible with the Block Placement Policy
   * used by the Namenode.
   */
  private static void checkReplicationPolicyCompatibility(Configuration conf
      ) throws UnsupportedActionException {
    BlockPlacementPolicies placementPolicies =
        new BlockPlacementPolicies(conf, null, NetworkTopology.getInstance(conf), null);
    if (!(placementPolicies.getPolicy(CONTIGUOUS) instanceof
        BlockPlacementPolicyDefault)) {
      throw new UnsupportedActionException(
          "Balancer without BlockPlacementPolicyDefault");
    }
  }

  static long getLong(Configuration conf, String key, long defaultValue) {
    final long v = conf.getLong(key, defaultValue);
    LOG.info(key + " = " + v + " (default=" + defaultValue + ")");
    if (v <= 0) {
      throw new HadoopIllegalArgumentException(key + " = " + v  + " <= " + 0);
    }
    return v;
  }

  static long getLongBytes(Configuration conf, String key, long defaultValue) {
    final long v = conf.getLongBytes(key, defaultValue);
    LOG.info(key + " = " + v + " (default=" + defaultValue + ")");
    if (v <= 0) {
      throw new HadoopIllegalArgumentException(key + " = " + v  + " <= " + 0);
    }
    return v;
  }

  static int getInt(Configuration conf, String key, int defaultValue) {
    final int v = conf.getInt(key, defaultValue);
    LOG.info(key + " = " + v + " (default=" + defaultValue + ")");
    if (v <= 0) {
      throw new HadoopIllegalArgumentException(key + " = " + v  + " <= " + 0);

View on GitHub (pinned to 2add963021)

Solutions

1. Find the key named in the exception message and set it to a positive value in hdfs-site.xml (or pass -Dkey=value via HADOOP_OPTS)
2. If you meant 'unlimited', use a very large positive value (e.g. 1t for size keys) rather than 0
3. Re-run the balancer and confirm the startup log line 'key = value (default=...)' shows your intended value

Example fix

// before
<property><name>dfs.balancer.max-size-to-move</name><value>0</value></property>

// after
<property><name>dfs.balancer.max-size-to-move</name><value>10737418240</value></property>

static void requirePositiveLong(Configuration conf, String key, long def) {
  long v = conf.getLong(key, def);
  if (v <= 0) throw new HadoopIllegalArgumentException(key + " = " + v + " <= 0");
}
// run for every long knob you set before invoking the balancer

catch (HadoopIllegalArgumentException e) { log.error("Balancer config rejected: {}", e.getMessage()); fixConfigAndRetry(); }

When it happens

Trigger: Any long-typed balancer knob resolved through Balancer.getLong with value <= 0 in the effective configuration, e.g. setting dfs.datanode.balance.bandwidthPerSec=0 or dfs.balancer.max-size-to-move=0 to try to 'disable' a limit - the helper rejects 0 as well as negatives.

Common situations: Operators trying to disable bandwidth throttling or size caps by setting them to 0; typos like a stray '-' sign; units confusion where 0 is legal for a different key but not for the ones routed through this helper.

Related errors

• Balancer without BlockPlacementPolicyDefault
• Requested replication factor of {replication}{err} for {src}
• dfs.datanode.parallel.volumes.load.threads.num = {} < 1
• Invalid values: dfs.bytes-per-checksum (={}) must divide cel
• Invalid checksum type: userOpt=${userOpt}, default=${default

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