apache/hadoop · error · DiskBalancerException

DATANODE_STATUS_NOT_REGULAR

DATANODE_STATUS_NOT_REGULAR

Error message

Datanode is in special state, e.g. Upgrade/Rollback etc. Disk balancing not permitted.

What it means

submitDiskBalancerPlan moves replicas between volumes, which is only safe on a normally running datanode. The implementation reads getStartupOption(getConf()) and refuses the request with DiskBalancerException Result.DATANODE_STATUS_NOT_REGULAR when the DN was started with any special option such as -upgrade or -rollback.

Source

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

    return tracer;
  }

  /**
   * Allows submission of a disk balancer Job.
   * @param planID  - Hash value of the plan.
   * @param planVersion - Plan version, reserved for future use. We have only
   *                    version 1 now.
   * @param planFile - Plan file name
   * @param planData - Actual plan data in json format
   * @throws IOException
   */
  @Override
  public void submitDiskBalancerPlan(String planID, long planVersion,
      String planFile, String planData, boolean skipDateCheck)
      throws IOException {
    checkSuperuserPrivilege();
    if (getStartupOption(getConf()) != StartupOption.REGULAR) {
      throw new DiskBalancerException(
          "Datanode is in special state, e.g. Upgrade/Rollback etc."
              + " Disk balancing not permitted.",
          DiskBalancerException.Result.DATANODE_STATUS_NOT_REGULAR);
    }

    getDiskBalancer().submitPlan(planID, planVersion, planFile, planData,
            skipDateCheck);
  }

  /**
   * Cancels a running plan.
   * @param planID - Hash string that identifies a plan
   */
  @Override
  public void cancelDiskBalancePlan(String planID) throws
      IOException {
    checkSuperuserPrivilege();
    getDiskBalancer().cancelPlan(planID);

View on GitHub (pinned to 2add963021)

Solutions

Restart the datanode with the default (REGULAR) startup option, then resubmit the plan
Inspect the DN's startup command line / startup option in configuration before generating or submitting a plan
Defer disk balancing until no upgrade/rollback is in progress on that node

Defensive patterns

Strategy: try-catch

Validate before calling

// Operator-side check before planning:
// inspect the target DN's startup command (ps -ef | grep DataNode)
// and confirm no -upgrade/-rollback/-rollingupgrade option is present.

Try / catch

try {
  dn.submitDiskBalancerPlan(planId, version, planFile, planData, skipDateCheck);
} catch (DiskBalancerException e) {
  if (e.getResult() == DiskBalancerException.Result.DATANODE_STATUS_NOT_REGULAR) {
    // reschedule after the DN restarts in REGULAR mode
  } else {
    throw e;
  }
}

Prevention

Run disk balancer plans only on DNs started with default startup options
Automate a pre-check of DN startup flags before 'hdfs diskbalancer -execute'
Do not schedule balancing jobs during upgrade/rollback maintenance windows

When it happens

Trigger: Calling ClientDatanodeProtocol.submitDiskBalancerPlan ('hdfs diskbalancer -execute/-submit') on a datanode whose startup option is not REGULAR (e.g. started with -rollingupgrade, -upgrade or -rollback flags).

Common situations: Attempting disk balancing during a rolling upgrade or rollback window; DN started with recovery flags left in startup scripts; leftover startup option in config/CLI from a previous maintenance action.

Related errors

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