apache/hadoop · error · IOException

DiskBalancer is not initialized

Error message

DiskBalancer is not initialized

What it means

DataNode constructs its DiskBalancer instance at startup only when disk balancing is enabled. getDiskBalancer() is the accessor behind every disk balancer RPC; when the field is null it throws this IOException, meaning dfs.disk.balancer.enabled was false when the process started.

Source

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

    for (Entry<String, Object> volume : volumeInfoMap.entrySet()) {
      @SuppressWarnings("unchecked")
      Map<String, Object> volumeInfo = (Map<String, Object>) volume.getValue();
      DatanodeVolumeInfo dnStorageInfo = new DatanodeVolumeInfo(
          volume.getKey(), (Long) volumeInfo.get("usedSpace"),
          (Long) volumeInfo.get("freeSpace"),
          (Long) volumeInfo.get("reservedSpace"),
          (Long) volumeInfo.get("reservedSpaceForReplicas"),
          (Long) volumeInfo.get("numBlocks"),
          (StorageType) volumeInfo.get("storageType"));
      volumeInfoList.add(dnStorageInfo);
    }
    return volumeInfoList;
  }

  @VisibleForTesting
  public DiskBalancer getDiskBalancer() throws IOException {
    if (this.diskBalancer == null) {
      throw new IOException("DiskBalancer is not initialized");
    }
    return this.diskBalancer;
  }

  /**
   * Construct DataTransfer in {@link DataNode#transferBlock}, the
   * BlockConstructionStage is PIPELINE_SETUP_CREATE and clientName is "".
   */
  private static boolean isTransfer(BlockConstructionStage stage,
      String clientName) {
    if (stage == PIPELINE_SETUP_CREATE && clientName.isEmpty()) {
      return true;
    }
    return false;
  }

  /**
   * Construct DataTransfer in

View on GitHub (pinned to 2add963021)

Solutions

1. Set dfs.disk.balancer.enabled=true in hdfs-site.xml on the datanode and restart it
2. Verify after restart with 'hdfs diskbalancer -query <datanode>'
3. Ensure generated plans only target datanodes where the feature is enabled

Example fix

<!-- before: property missing => disk balancer disabled -->
<!-- after -->
<property>
  <name>dfs.disk.balancer.enabled</name>
  <value>true</value>
</property>
<!-- then restart the DataNode -->

Configuration conf = new Configuration();
if (!conf.getBoolean(DFSConfigKeys.DFS_DISK_BALANCER_ENABLED, false)) {
  throw new IllegalStateException(
      "Enable dfs.disk.balancer.enabled and restart the DataNode before using disk balancer APIs");
}

catch (IOException e) {
  if ("DiskBalancer is not initialized".equals(e.getMessage())) {
    // DN started with dfs.disk.balancer.enabled=false: fix config + restart
  } else { throw e; }
}

When it happens

Trigger: Invoking any disk balancer API - submitDiskBalancerPlan, cancelDiskBalancerPlan, queryDiskBalancerPlan, getDiskBalancerSetting, getDiskBalancerVolumeNames - on a datanode started with dfs.disk.balancer.enabled=false.

Common situations: Fresh cluster where dfs.disk.balancer.enabled was never set; enabling the flag in config but forgetting to restart the DN; mixed clusters where only some DNs have the feature enabled.

Related errors

• UNKNOWN_KEY
• Not a valid Boolean value for {property} in reconfSlowPeerPa
• Not a valid Boolean value for {property}
• No directory is specified.
• Invalid value configured for dfs.datanode.failed.volumes.tol

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