apache/hadoop · error · RuntimeException

The parse failed because of bad layoutversion value

Error message

The parse failed because of bad layoutversion value

What it means

The first content check inside <configuration>: the <layoutversion> element must parse as an integer and equal 1 (LAYOUT_VERSION in ECPolicyLoader), the only policy-file format generation this Hadoop version understands. A value that parses but differs (0, 2, -1) produces 'The parse failed because of bad layoutversion value'. The check stops files from a different format generation from being silently misread.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/util/ECPolicyLoader.java:119

    }

    List<ErasureCodingPolicy> policies;
    if (root.getElementsByTagName("layoutversion").getLength() > 0) {
      if (loadLayoutVersion(root) == LAYOUT_VERSION) {
        if (root.getElementsByTagName("schemas").getLength() > 0) {
          Map<String, ECSchema> schemas = loadSchemas(root);
          if (root.getElementsByTagName("policies").getLength() > 0) {
            policies = loadPolicies(root, schemas);
          } else {
            throw new RuntimeException("Bad EC policy configuration file: "
                + "no <policies> element");
          }
        } else {
          throw new RuntimeException("Bad EC policy configuration file: "
              + "no <schemas> element");
        }
      } else {
        throw new RuntimeException("The parse failed because of "
            + "bad layoutversion value");
      }
    } else {
      throw new RuntimeException("Bad EC policy configuration file: "
          + "no <layoutVersion> element");
    }

    return policies;
  }

  /**
   * Load layoutVersion from root element in the XML configuration file.
   * @param root root element
   * @return layout version
   */
  private int loadLayoutVersion(Element root) {
    int layoutVersion;
    Text text = (Text) root.getElementsByTagName("layoutversion")

View on GitHub (pinned to 2add963021)

Solutions

1. Set <layoutversion>1</layoutversion> - the only supported value in this codebase
2. Regenerate the file from the user-ec-policies.xml template shipped with your exact Hadoop version
3. If the file came from another cluster version, re-express its schemas and policies in this version's template rather than just editing the number

Example fix

<!-- before -->
<layoutversion>0</layoutversion>

<!-- after -->
<layoutversion>1</layoutversion>

NodeList lv = doc.getDocumentElement().getElementsByTagName("layoutversion");
if (lv.getLength() == 0
    || Integer.parseInt(lv.item(0).getFirstChild().getNodeValue().trim()) != 1) {
  // only layout version 1 is supported by this loader
}

try {
  new ECPolicyLoader().loadPolicy(path);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().contains("bad layoutversion value")) {
    // set <layoutversion>1</layoutversion> or regenerate the file from this version's template
  } else { throw e; }
}

When it happens

Trigger: `hdfs ec -addPolicies -policyFile` with <layoutversion> set to anything other than 1 - usually a file taken from a different Hadoop release whose format generation differs, or a hand-written file that guessed the value.

Common situations: Policy files copied between Hadoop versions; files authored from outdated documentation; a leftover 0 from early custom setups.

Related errors

• Failed to load EC policy file: {policyFilePath}
• Bad EC policy configuration file: top-level element not <con
• Bad EC policy configuration file: no <policies> element
• Bad EC policy configuration file: no <schemas> element
• Bad EC policy configuration file: no <layoutVersion> element

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