{"record":{"id":"5b3d040d6224d5cd","repo":"apache/hadoop","slug":"diskbalancer-is-not-initialized","errorCode":null,"errorMessage":"DiskBalancer is not initialized","messagePattern":"DiskBalancer is not initialized","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DataNode.java","lineNumber":4374,"sourceCode":"    for (Entry<String, Object> volume : volumeInfoMap.entrySet()) {\n      @SuppressWarnings(\"unchecked\")\n      Map<String, Object> volumeInfo = (Map<String, Object>) volume.getValue();\n      DatanodeVolumeInfo dnStorageInfo = new DatanodeVolumeInfo(\n          volume.getKey(), (Long) volumeInfo.get(\"usedSpace\"),\n          (Long) volumeInfo.get(\"freeSpace\"),\n          (Long) volumeInfo.get(\"reservedSpace\"),\n          (Long) volumeInfo.get(\"reservedSpaceForReplicas\"),\n          (Long) volumeInfo.get(\"numBlocks\"),\n          (StorageType) volumeInfo.get(\"storageType\"));\n      volumeInfoList.add(dnStorageInfo);\n    }\n    return volumeInfoList;\n  }\n\n  @VisibleForTesting\n  public DiskBalancer getDiskBalancer() throws IOException {\n    if (this.diskBalancer == null) {\n      throw new IOException(\"DiskBalancer is not initialized\");\n    }\n    return this.diskBalancer;\n  }\n\n  /**\n   * Construct DataTransfer in {@link DataNode#transferBlock}, the\n   * BlockConstructionStage is PIPELINE_SETUP_CREATE and clientName is \"\".\n   */\n  private static boolean isTransfer(BlockConstructionStage stage,\n      String clientName) {\n    if (stage == PIPELINE_SETUP_CREATE && clientName.isEmpty()) {\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Construct DataTransfer in","sourceCodeStart":4356,"sourceCodeEnd":4392,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DataNode.java#L4356-L4392","documentation":"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.","triggerScenarios":"Invoking any disk balancer API - submitDiskBalancerPlan, cancelDiskBalancerPlan, queryDiskBalancerPlan, getDiskBalancerSetting, getDiskBalancerVolumeNames - on a datanode started with dfs.disk.balancer.enabled=false.","commonSituations":"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.","solutions":["Set dfs.disk.balancer.enabled=true in hdfs-site.xml on the datanode and restart it","Verify after restart with 'hdfs diskbalancer -query <datanode>'","Ensure generated plans only target datanodes where the feature is enabled"],"exampleFix":"<!-- before: property missing => disk balancer disabled -->\n<!-- after -->\n<property>\n  <name>dfs.disk.balancer.enabled</name>\n  <value>true</value>\n</property>\n<!-- then restart the DataNode -->","handlingStrategy":"validation","validationCode":"Configuration conf = new Configuration();\nif (!conf.getBoolean(DFSConfigKeys.DFS_DISK_BALANCER_ENABLED, false)) {\n  throw new IllegalStateException(\n      \"Enable dfs.disk.balancer.enabled and restart the DataNode before using disk balancer APIs\");\n}","typeGuard":null,"tryCatchPattern":"catch (IOException e) {\n  if (\"DiskBalancer is not initialized\".equals(e.getMessage())) {\n    // DN started with dfs.disk.balancer.enabled=false: fix config + restart\n  } else { throw e; }\n}","preventionTips":["Set dfs.disk.balancer.enabled=true on all DNs that will receive plans, and restart them","Verify with 'hdfs diskbalancer -query <host>' before executing plans","Remember config changes need a DN restart - a reconfig is not enough for this flag"],"tags":["hadoop","hdfs","datanode","diskbalancer","configuration"],"backgroundTag":"feature-not-enabled","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}