apache/hadoop · error · HadoopIllegalArgumentException

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

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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Balancer without BlockPlacementPolicyDefault
• dfs.datanode.parallel.volumes.load.threads.num =
• Invalid checksum type: userOpt=
• Invalid values: dfs.bytes-per-checksum
• Limit is negative.

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

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