apache/hadoop · error · RuntimeException

Bad EC policy configuration file: no <schemas> element

Error message

Bad EC policy configuration file: no <schemas> element

What it means

The second structural check: <schemas> must declare the EC schemas (codec, data/parity units) that <policies> reference by name. If <layoutversion> is present and correct but <schemas> is absent, policies would reference undefined schemas, so loading aborts with 'Bad EC policy configuration file: no <schemas> element'.

Source

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

    if (!"configuration".equals(root.getTagName())) {
      throw new RuntimeException("Bad EC policy configuration file: "
          + "top-level element not <configuration>");
    }

    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

View on GitHub (pinned to 2add963021)

Solutions

1. Add a <schemas> section declaring each schema once (id, codec, data units, parity units)
2. Reference schemas from policies by name via <schemaId> and make sure every reference has a matching declaration
3. Model the file on the shipped user-ec-policies.xml example

Example fix

<!-- before: policies only, schemas undefined -->
<configuration>
  <layoutversion>1</layoutversion>
  <policies><policy><name>P</name><schemaId>MY-SCHEMA</schemaId></policy></policies>
</configuration>

<!-- after -->
<configuration>
  <layoutversion>1</layoutversion>
  <schemas><schema><id>MY-SCHEMA</id><!-- codec, units... --></schema></schemas>
  <policies><policy><name>P</name><schemaId>MY-SCHEMA</schemaId></policy></policies>
</configuration>

Element root = doc.getDocumentElement();
boolean hasSchemas = root.getElementsByTagName("schemas").getLength() > 0;
if (!hasSchemas) { /* reject before loadPolicy */ }

try {
  new ECPolicyLoader().loadPolicy(path);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().contains("no <schemas> element")) {
    // declare schemas once in <schemas> and reference them by id from policies
  } else { throw e; }
}

When it happens

Trigger: `hdfs ec -addPolicies` with a file that skips <schemas> and inlines codec parameters directly inside each <policy> - the format requires schemas to be declared separately and referenced by name.

Common situations: Users inlining schema parameters into policies; files written against an imagined simpler format; the schemas block deleted because it looked redundant.

Related errors

• Bad EC policy configuration file: no <policies> element
• Bad EC policy configuration file: top-level element not <con
• Bad element in EC policy configuration file: {tagName}
• Value of <{tagName}> is null
• Bad policy is found in EC policy configuration file

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