What causes "Disk Balancer is not enabled." in apache/hadoop?

Set dfs.datanode.disk.balancer.enabled=true in hdfs-site.xml on the DataNodes (this is a DataNode-side setting)

apache/hadoop · error · DiskBalancerException

DISK_BALANCER_NOT_ENABLED

DISK_BALANCER_NOT_ENABLED

Error message

Disk Balancer is not enabled.

What it means

DiskBalancerException with Result.DISK_BALANCER_NOT_ENABLED from DiskBalancer.checkDiskBalancerEnabled, the guard at the top of every disk-balancer operation (submitPlan, cancelPlan, getVolumeNames, query bandwidth, etc.). The DataNode only accepts disk-balancer commands when dfs.datanode.disk.balancer.enabled is true - it defaults to false, so a freshly installed or unconfigured cluster rejects all disk balancer operations with this error.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DiskBalancer.java:340

  public long getBandwidth() throws DiskBalancerException {
    lock.lock();
    try {
      checkDiskBalancerEnabled();
      return this.bandwidth;
    } finally {
      lock.unlock();
    }
  }

  /**
   * Throws if Disk balancer is disabled.
   *
   * @throws DiskBalancerException
   */
  private void checkDiskBalancerEnabled()
      throws DiskBalancerException {
    if (!isDiskBalancerEnabled) {
      throw new DiskBalancerException("Disk Balancer is not enabled.",
          DiskBalancerException.Result.DISK_BALANCER_NOT_ENABLED);
    }
  }

  /**
   * Sets Disk balancer is to enable or not to enable.
   *
   * @param diskBalancerEnabled
   *          true, enable diskBalancer, otherwise false to disable it.
   */
  public void setDiskBalancerEnabled(boolean diskBalancerEnabled) {
    isDiskBalancerEnabled = diskBalancerEnabled;
  }

  /**
   * Returns the value indicating if diskBalancer is enabled.
   *
   * @return boolean.

View on GitHub (pinned to 2add963021)

Solutions

Set dfs.datanode.disk.balancer.enabled=true in hdfs-site.xml on the DataNodes (this is a DataNode-side setting)
Restart the DataNodes (or use dfsadmin -reconfig if supported in your version) so the flag takes effect
Re-run the diskbalancer command and confirm the error is gone before generating plans

Example fix

<!-- before: missing on DataNodes -> DISK_BALANCER_NOT_ENABLED -->
<!-- after: add to hdfs-site.xml on every DataNode and restart -->
<property>
  <name>dfs.datanode.disk.balancer.enabled</name>
  <value>true</value>
</property>

Defensive patterns

Strategy: validation

Validate before calling

// Client/ops check before any diskbalancer command
Configuration conf = new Configuration();
if (!conf.getBoolean("dfs.datanode.disk.balancer.enabled", false)) {
  throw new IllegalStateException(
      "Set dfs.datanode.disk.balancer.enabled=true in hdfs-site.xml on the DataNodes and restart them");
}
// now safe to run: hdfs diskbalancer -plan <node>

Try / catch

try {
  diskBalancer.submitPlan(...);
} catch (DiskBalancerException e) {
  if (e.getResult() == DiskBalancerException.Result.DISK_BALANCER_NOT_ENABLED) {
    // enable the flag on the DataNode config and restart DN, then retry the command
  }
}

Prevention

Include dfs.datanode.disk.balancer.enabled=true in the baseline DataNode hdfs-site.xml for clusters that will use it
Remember it is a DataNode-side flag - setting it only on clients or the NameNode does nothing
Add a config-lint step to provisioning that asserts the flag on every DN before you need disk balancing in an incident

When it happens

Trigger: Any 'hdfs diskbalancer' command (execute/cancel/query/report/bandwidth) against a DataNode where dfs.datanode.disk.balancer.enabled is unset or false. DiskBalancer is a separate feature from the regular HDFS balancer; enabling the latter does not enable this one.

Common situations: New cluster or new nodes provisioned from a template missing the setting; operators assuming 'hdfs balancer' and disk balancer share a config; setting the key only on the client or only on the NameNode instead of DataNodes.

Related errors

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