{"record":{"id":"9c286370d8a8ba84","repo":"apache/hadoop","slug":"datanode-status-not-regular","errorCode":"DATANODE_STATUS_NOT_REGULAR","errorMessage":"Datanode is in special state, e.g. Upgrade/Rollback etc. Disk balancing not permitted.","messagePattern":"Datanode is in special state, e\\.g\\. Upgrade/Rollback etc\\. Disk balancing not permitted\\.","errorType":"exception","errorClass":"DiskBalancerException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DataNode.java","lineNumber":4267,"sourceCode":"    return tracer;\n  }\n\n  /**\n   * Allows submission of a disk balancer Job.\n   * @param planID  - Hash value of the plan.\n   * @param planVersion - Plan version, reserved for future use. We have only\n   *                    version 1 now.\n   * @param planFile - Plan file name\n   * @param planData - Actual plan data in json format\n   * @throws IOException\n   */\n  @Override\n  public void submitDiskBalancerPlan(String planID, long planVersion,\n      String planFile, String planData, boolean skipDateCheck)\n      throws IOException {\n    checkSuperuserPrivilege();\n    if (getStartupOption(getConf()) != StartupOption.REGULAR) {\n      throw new DiskBalancerException(\n          \"Datanode is in special state, e.g. Upgrade/Rollback etc.\"\n              + \" Disk balancing not permitted.\",\n          DiskBalancerException.Result.DATANODE_STATUS_NOT_REGULAR);\n    }\n\n    getDiskBalancer().submitPlan(planID, planVersion, planFile, planData,\n            skipDateCheck);\n  }\n\n  /**\n   * Cancels a running plan.\n   * @param planID - Hash string that identifies a plan\n   */\n  @Override\n  public void cancelDiskBalancePlan(String planID) throws\n      IOException {\n    checkSuperuserPrivilege();\n    getDiskBalancer().cancelPlan(planID);","sourceCodeStart":4249,"sourceCodeEnd":4285,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DataNode.java#L4249-L4285","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Operator-side check before planning:\n// inspect the target DN's startup command (ps -ef | grep DataNode)\n// and confirm no -upgrade/-rollback/-rollingupgrade option is present.","typeGuard":null,"tryCatchPattern":"try {\n  dn.submitDiskBalancerPlan(planId, version, planFile, planData, skipDateCheck);\n} catch (DiskBalancerException e) {\n  if (e.getResult() == DiskBalancerException.Result.DATANODE_STATUS_NOT_REGULAR) {\n    // reschedule after the DN restarts in REGULAR mode\n  } else {\n    throw e;\n  }\n}","preventionTips":["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"],"tags":["hadoop","hdfs","datanode","diskbalancer","startup-options","upgrade"],"backgroundTag":"invalid-node-state","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}