{"record":{"id":"47914b9111ba5a02","repo":"apache/hadoop","slug":"disk-balancer-not-enabled","errorCode":"DISK_BALANCER_NOT_ENABLED","errorMessage":"Disk Balancer is not enabled.","messagePattern":"Disk Balancer is not enabled\\.","errorType":"exception","errorClass":"DiskBalancerException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DiskBalancer.java","lineNumber":340,"sourceCode":"  public long getBandwidth() throws DiskBalancerException {\n    lock.lock();\n    try {\n      checkDiskBalancerEnabled();\n      return this.bandwidth;\n    } finally {\n      lock.unlock();\n    }\n  }\n\n  /**\n   * Throws if Disk balancer is disabled.\n   *\n   * @throws DiskBalancerException\n   */\n  private void checkDiskBalancerEnabled()\n      throws DiskBalancerException {\n    if (!isDiskBalancerEnabled) {\n      throw new DiskBalancerException(\"Disk Balancer is not enabled.\",\n          DiskBalancerException.Result.DISK_BALANCER_NOT_ENABLED);\n    }\n  }\n\n  /**\n   * Sets Disk balancer is to enable or not to enable.\n   *\n   * @param diskBalancerEnabled\n   *          true, enable diskBalancer, otherwise false to disable it.\n   */\n  public void setDiskBalancerEnabled(boolean diskBalancerEnabled) {\n    isDiskBalancerEnabled = diskBalancerEnabled;\n  }\n\n  /**\n   * Returns the value indicating if diskBalancer is enabled.\n   *\n   * @return boolean.","sourceCodeStart":322,"sourceCodeEnd":358,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DiskBalancer.java#L322-L358","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"<!-- before: missing on DataNodes -> DISK_BALANCER_NOT_ENABLED -->\n<!-- after: add to hdfs-site.xml on every DataNode and restart -->\n<property>\n  <name>dfs.datanode.disk.balancer.enabled</name>\n  <value>true</value>\n</property>","handlingStrategy":"validation","validationCode":"// Client/ops check before any diskbalancer command\nConfiguration conf = new Configuration();\nif (!conf.getBoolean(\"dfs.datanode.disk.balancer.enabled\", false)) {\n  throw new IllegalStateException(\n      \"Set dfs.datanode.disk.balancer.enabled=true in hdfs-site.xml on the DataNodes and restart them\");\n}\n// now safe to run: hdfs diskbalancer -plan <node>","typeGuard":null,"tryCatchPattern":"try {\n  diskBalancer.submitPlan(...);\n} catch (DiskBalancerException e) {\n  if (e.getResult() == DiskBalancerException.Result.DISK_BALANCER_NOT_ENABLED) {\n    // enable the flag on the DataNode config and restart DN, then retry the command\n  }\n}","preventionTips":["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"],"tags":["hdfs","diskbalancer","configuration","feature-flag","dfsadmin"],"backgroundTag":"feature-not-enabled","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}