apache/hadoop · error · RuntimeException

Bad EC policy configuration file: no <layoutVersion> element

Error message

Bad EC policy configuration file: no <layoutVersion> element

What it means

Thrown by ECPolicyLoader.loadPolicy(), the parser behind `hdfs ec -loadPolicy <file>`, when the EC policy XML root <configuration> contains no <layoutversion> child. The check uses root.getElementsByTagName("layoutversion"), which is case-sensitive in XML DOM, so both a missing element and a camelCase <layoutVersion> spelling fail. The layout version identifies the file format; the loader only accepts version 1 (ECPolicyLoader.LAYOUT_VERSION).

Source

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

      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")
        .item(0).getFirstChild();
    if (text != null) {
      String value = text.getData().trim();
      try {

View on GitHub (pinned to 2add963021)

Solutions

1. Add <layoutversion>1</layoutversion> (lowercase tag, integer value 1) as a direct child of <configuration>
2. Start from the shipped user_ec_policies.xml.template and edit only the <schema>/<policy> entries
3. Validate before loading: xmllint --xpath 'count(/configuration/layoutversion)' file.xml must return 1
4. Confirm the root element is exactly <configuration>; other roots are rejected earlier with a different message

Example fix

<!-- before -->
<configuration>
  <schemas>...</schemas>
</configuration>

<!-- after -->
<configuration>
  <layoutversion>1</layoutversion>
  <schemas>...</schemas>
</configuration>

Document doc = XMLUtils.newSecureDocumentBuilderFactory().newDocumentBuilder()
    .parse(new File(policyFilePath));
if (!"configuration".equals(doc.getDocumentElement().getTagName())
    || doc.getElementsByTagName("layoutversion").getLength() == 0) {
  throw new IllegalArgumentException(
      policyFilePath + " lacks <layoutversion> under <configuration>; fix before loadPolicy()");
}

try {
  List<ErasureCodingPolicy> ps = new ECPolicyLoader().loadPolicy(path);
} catch (RuntimeException e) {
  // message names the structural defect; include the file path in operator output
  LOG.error("EC policy file {} rejected: {}", path, e.getMessage());
}

When it happens

Trigger: Run `hdfs ec -loadPolicy ec-policy.xml` where the file omits <layoutversion>, spells it <layoutVersion> (does not match the lowercase DOM query), or nests it outside the <configuration> root element.

Common situations: Hand-writing the policy file from a blog post, trimming the shipped user_ec_policies.xml.template too aggressively, or pasting content from a *-site.xml config that has no layoutversion element.

Related errors

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

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