{"record":{"id":"9e26aa40a59bfdb2","repo":"apache/hadoop","slug":"invalid-plan-version","errorCode":"INVALID_PLAN_VERSION","errorMessage":"Invalid plan version.","messagePattern":"Invalid plan version\\.","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":431,"sourceCode":"    if (!force) {\n      verifyTimeStamp(nodePlan);\n    }\n    verifyNodeUUID(nodePlan);\n    return nodePlan;\n  }\n\n  /**\n   * Verifies the plan version is something that we support.\n   *\n   * @param planVersion - Long version.\n   * @throws DiskBalancerException\n   */\n  private void verifyPlanVersion(long planVersion)\n      throws DiskBalancerException {\n    if ((planVersion < DiskBalancerConstants.DISKBALANCER_MIN_VERSION) ||\n        (planVersion > DiskBalancerConstants.DISKBALANCER_MAX_VERSION)) {\n      LOG.error(\"Disk Balancer - Invalid plan version.\");\n      throw new DiskBalancerException(\"Invalid plan version.\",\n          DiskBalancerException.Result.INVALID_PLAN_VERSION);\n    }\n  }\n\n  /**\n   * Verifies that plan matches the SHA-1 provided by the client.\n   *\n   * @param planID - SHA-1 Hex Bytes\n   * @param plan   - Plan String\n   * @throws DiskBalancerException\n   */\n  private NodePlan verifyPlanHash(String planID, String plan)\n      throws DiskBalancerException {\n    final long sha1Length = 40;\n    if (plan == null || plan.length() == 0) {\n      LOG.error(\"Disk Balancer -  Invalid plan.\");\n      throw new DiskBalancerException(\"Invalid plan.\",\n          DiskBalancerException.Result.INVALID_PLAN);","sourceCodeStart":413,"sourceCodeEnd":449,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DiskBalancer.java#L413-L449","documentation":"DiskBalancerException with Result.INVALID_PLAN_VERSION from DiskBalancer.verifyPlanVersion: the submitted plan file's version field lies outside the range this DataNode understands (bounded by DiskBalancerConstants.DISKBALANCER_MIN_VERSION=1 and DISKBALANCER_MAX_VERSION=1 in this release). Plan files carry a schema version generated by the plan tool; a DataNode refuses plans whose version it cannot parse safely rather than guess at the format.","triggerScenarios":"Executing a plan file whose version field is not 1: plans generated by a different (older or newer) Hadoop release whose NodePlan schema changed, or hand-edited/renamed plan files with a mangled version field; 'hdfs diskbalancer -execute <file>' submits planVersion from the JSON header.","commonSituations":"Plan generated on one release then executed against DataNodes on another during rolling upgrades; mixed-version clusters; stale plan files kept around from previous major versions; plans copied between clusters.","solutions":["Regenerate the plan on the same Hadoop release as the target DataNodes: 'hdfs diskbalancer -plan <node>' with the matching binaries, then -execute the fresh file","Check the version field inside the plan JSON header and compare with DiskBalancerConstants min/max (1..1 here)","Finish aligning cluster versions before disk balancing across mixed-version nodes"],"exampleFix":"# before: plan from another release -> INVALID_PLAN_VERSION\nhdfs diskbalancer -execute /system/diskbalancer/old-node-plan.json\n\n# after: regenerate with the release the DN runs, then execute\nhdfs diskbalancer -plan <datanode>\nhdfs diskbalancer -execute /system/diskbalancer/<node>-plan.json","handlingStrategy":"validation","validationCode":"// Verify plan version is within the range this cluster understands before execute\n// (here: DiskBalancerConstants.DISKBALANCER_MIN_VERSION=1, MAX=1)\nNodePlan plan = NodePlan.parseJson(planData);\nif (plan.getVersion() < 1 || plan.getVersion() > 1) {\n  throw new IllegalArgumentException(\n      \"Plan version \" + plan.getVersion() + \" unsupported - regenerate the plan \"\n      + \"with the Hadoop release the DataNodes run\");\n}\nhdfsDiskBalancerExecute(planData);","typeGuard":null,"tryCatchPattern":"try {\n  diskBalancer.submitPlan(planId, planVersion, planFile, planData, force);\n} catch (DiskBalancerException e) {\n  if (e.getResult() == DiskBalancerException.Result.INVALID_PLAN_VERSION) {\n    // plan came from a different release: regenerate with matching binaries and resubmit\n  }\n}","preventionTips":["Generate plans with the exact Hadoop release the target DataNodes run (verify with 'hdfs version')","Do not reuse plan files across releases or clusters - regenerate per target and per run","During rolling upgrades, wait for version convergence before running disk balancing"],"tags":["hdfs","diskbalancer","plan-version","version-mismatch","rolling-upgrade"],"backgroundTag":"version-not-supported","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}