apache/hadoop · error · RuntimeException

Bad EC policy configuration file: top-level element not <con

Error message

Bad EC policy configuration file: top-level element not <configuration>

What it means

The EC policy file must be a Hadoop-style <configuration> document; ECPolicyLoader checks the root element's tag name immediately after parsing. Any other root - <policies>, <ecPolicies>, a wrapper element from another tool - is rejected with RuntimeException 'Bad EC policy configuration file: top-level element not <configuration>'.

Source

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

   * @return list of EC policies
   * @throws ParserConfigurationException if ParserConfigurationException happen
   * @throws IOException if no such EC policy file
   * @throws SAXException if the xml file has some invalid elements
   */
  private List<ErasureCodingPolicy> loadECPolicies(File policyFile)
      throws ParserConfigurationException, IOException, SAXException {

    LOG.info("Loading EC policy file " + policyFile);

    // Read and parse the EC policy file.
    DocumentBuilderFactory dbf = XMLUtils.newSecureDocumentBuilderFactory();
    dbf.setIgnoringComments(true);
    DocumentBuilder builder = dbf.newDocumentBuilder();
    Document doc = builder.parse(policyFile);
    Element root = doc.getDocumentElement();

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

View on GitHub (pinned to 2add963021)

Solutions

Wrap the entire content in <configuration> ... </configuration> as the outermost element
Start from the shipped user-ec-policies.xml skeleton and fill in layoutversion, schemas and policies
Re-run xmllint --noout after editing to confirm well-formedness

Example fix

<!-- before -->
<policies>
  <policy>...</policy>
</policies>

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

Defensive patterns

Strategy: validation

Validate before calling

Document doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(file);
if (!"configuration".equals(doc.getDocumentElement().getTagName())) {
  // reject before calling ECPolicyLoader.loadPolicy
}

Try / catch

try {
  new ECPolicyLoader().loadPolicy(path);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().contains("top-level element not <configuration>")) {
    // wrap file contents in a <configuration> root and retry
  } else { throw e; }
}

Prevention

Always start policy files from the version's shipped template
Automate a structure check (root element + required children) in config CI

When it happens

Trigger: `hdfs ec -addPolicies -policyFile` on an XML whose outermost element is not exactly <configuration>: a file exported or hand-assembled around a different root element.

Common situations: Users wrapping policies in their own root element; converting from other config formats; copy-paste from documentation that omits the outer element.

Related errors

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