What causes "Invalid plan." in apache/hadoop?

Inspect the plan file: ls -l and head the JSON - it must be non-empty and start with the NodePlan JSON structure

apache/hadoop · error · DiskBalancerException

INVALID_PLAN

INVALID_PLAN

Error message

Invalid plan.

What it means

DiskBalancerException with Result.INVALID_PLAN from DiskBalancer.verifyPlanHash: the submitted plan string is null or empty. Before any hash comparison or JSON parsing happens, the DataNode rejects a plan payload with no content - meaning the client sent no plan data at all, not merely a bad one.

Source

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

      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);
    }

    if ((planID == null) ||
        (planID.length() != sha1Length) ||
        !DigestUtils.sha1Hex(plan.getBytes(StandardCharsets.UTF_8))
            .equalsIgnoreCase(planID)) {
      LOG.error("Disk Balancer - Invalid plan hash.");
      throw new DiskBalancerException("Invalid or mis-matched hash.",
          DiskBalancerException.Result.INVALID_PLAN_HASH);
    }

    try {
      return NodePlan.parseJson(plan);
    } catch (IOException ex) {
      throw new DiskBalancerException("Parsing plan failed.", ex,
          DiskBalancerException.Result.MALFORMED_PLAN);
    }

View on GitHub (pinned to 2add963021)

Solutions

Inspect the plan file: ls -l and head the JSON - it must be non-empty and start with the NodePlan JSON structure
Regenerate the plan with 'hdfs diskbalancer -plan <node>' and execute the newly written file
If calling submitPlan programmatically, read the plan file fully into planData before submitting and assert non-empty

Example fix

# before: zero-byte/truncated plan -> INVALID_PLAN
ls -l /system/diskbalancer/node-plan.json   # 0 bytes
hdfs diskbalancer -execute /system/diskbalancer/node-plan.json

# after: regenerate and verify content before executing
hdfs diskbalancer -plan <datanode>
head -c 200 /system/diskbalancer/<node>-plan.json   # sane JSON?
hdfs diskbalancer -execute /system/diskbalancer/<node>-plan.json

Defensive patterns

Strategy: validation

Validate before calling

// Reject empty plans before submission
String planData = new String(Files.readAllBytes(Paths.get(planFile)),
    StandardCharsets.UTF_8);
if (planData == null || planData.trim().isEmpty()) {
  throw new IllegalArgumentException(
      "Plan file empty: " + planFile + " - regenerate with 'hdfs diskbalancer -plan'");
}
diskBalancer.submitPlan(planId, planVersion, planFile, planData, force);

Try / catch

try {
  diskBalancer.submitPlan(planId, planVersion, planFile, planData, force);
} catch (DiskBalancerException e) {
  if (e.getResult() == DiskBalancerException.Result.INVALID_PLAN
      && (planData == null || planData.isEmpty())) {
    // payload was empty: regenerate the plan file and resubmit non-empty data
  }
}

Prevention

Sanity-check plan files (non-zero size, starts with '{') before -execute
Capture 'hdfs diskbalancer -plan' output to its own file without piping through filters that can empty it
In automation, assert planData.trim().length() > 0 before calling submitPlan

When it happens

Trigger: 'hdfs diskbalancer -execute' where the plan data read from the plan file is empty: empty/truncated plan file, wrong path resolving to a zero-byte file, or API callers (submitPlan) passing null/empty planData programmatically.

Common situations: Interrupted plan generation leaving a 0-byte plan file; passing a directory or wrong filename to -execute; scripts that capture command output into the plan file incorrectly; programmatic use of DiskBalancer.submitPlan with an unread plan.

Related errors

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