apache/hadoop · error · DiskBalancerException

INVALID_PLAN_VERSION

INVALID_PLAN_VERSION

Error message

Invalid plan version.

What it means

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.

Source

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

    if (!force) {
      verifyTimeStamp(nodePlan);
    }
    verifyNodeUUID(nodePlan);
    return nodePlan;
  }

  /**
   * Verifies the plan version is something that we support.
   *
   * @param planVersion - Long version.
   * @throws DiskBalancerException
   */
  private void verifyPlanVersion(long planVersion)
      throws DiskBalancerException {
    if ((planVersion < DiskBalancerConstants.DISKBALANCER_MIN_VERSION) ||
        (planVersion > DiskBalancerConstants.DISKBALANCER_MAX_VERSION)) {
      LOG.error("Disk Balancer - Invalid plan version.");
      throw new DiskBalancerException("Invalid plan version.",
          DiskBalancerException.Result.INVALID_PLAN_VERSION);
    }
  }

  /**
   * Verifies that plan matches the SHA-1 provided by the client.
   *
   * @param planID - SHA-1 Hex Bytes
   * @param plan   - Plan String
   * @throws DiskBalancerException
   */
  private NodePlan verifyPlanHash(String planID, String plan)
      throws DiskBalancerException {
    final long sha1Length = 40;
    if (plan == null || plan.length() == 0) {
      LOG.error("Disk Balancer -  Invalid plan.");
      throw new DiskBalancerException("Invalid plan.",
          DiskBalancerException.Result.INVALID_PLAN);

View on GitHub (pinned to 2add963021)

Solutions

1. 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
2. Check the version field inside the plan JSON header and compare with DiskBalancerConstants min/max (1..1 here)
3. Finish aligning cluster versions before disk balancing across mixed-version nodes

Example fix

# before: plan from another release -> INVALID_PLAN_VERSION
hdfs diskbalancer -execute /system/diskbalancer/old-node-plan.json

# after: regenerate with the release the DN runs, then execute
hdfs diskbalancer -plan <datanode>
hdfs diskbalancer -execute /system/diskbalancer/<node>-plan.json

// Verify plan version is within the range this cluster understands before execute
// (here: DiskBalancerConstants.DISKBALANCER_MIN_VERSION=1, MAX=1)
NodePlan plan = NodePlan.parseJson(planData);
if (plan.getVersion() < 1 || plan.getVersion() > 1) {
  throw new IllegalArgumentException(
      "Plan version " + plan.getVersion() + " unsupported - regenerate the plan "
      + "with the Hadoop release the DataNodes run");
}
hdfsDiskBalancerExecute(planData);

try {
  diskBalancer.submitPlan(planId, planVersion, planFile, planData, force);
} catch (DiskBalancerException e) {
  if (e.getResult() == DiskBalancerException.Result.INVALID_PLAN_VERSION) {
    // plan came from a different release: regenerate with matching binaries and resubmit
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unexpected blockChecksumType '%s', expecting COMPOSITE_CRC
• Cannot load data from ZooKeeper; itwas written with a newer
• Version Mismatch (Expected: {}, Received: {} )
• The \"downgrade\" option is no longer supported since it may
• Failed to convert \"{s}\" to RollingUpgradeStartupOption

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