{"record":{"id":"a857903acc956212","repo":"apache/hadoop","slug":"bad-ec-policy-configuration-file-top-level-elemen","errorCode":null,"errorMessage":"Bad EC policy configuration file: top-level element not <configuration>","messagePattern":"Bad EC policy configuration file: top-level element not <configuration>","errorType":"validation","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/util/ECPolicyLoader.java","lineNumber":99,"sourceCode":"   * @return list of EC policies\n   * @throws ParserConfigurationException if ParserConfigurationException happen\n   * @throws IOException if no such EC policy file\n   * @throws SAXException if the xml file has some invalid elements\n   */\n  private List<ErasureCodingPolicy> loadECPolicies(File policyFile)\n      throws ParserConfigurationException, IOException, SAXException {\n\n    LOG.info(\"Loading EC policy file \" + policyFile);\n\n    // Read and parse the EC policy file.\n    DocumentBuilderFactory dbf = XMLUtils.newSecureDocumentBuilderFactory();\n    dbf.setIgnoringComments(true);\n    DocumentBuilder builder = dbf.newDocumentBuilder();\n    Document doc = builder.parse(policyFile);\n    Element root = doc.getDocumentElement();\n\n    if (!\"configuration\".equals(root.getTagName())) {\n      throw new RuntimeException(\"Bad EC policy configuration file: \"\n          + \"top-level element not <configuration>\");\n    }\n\n    List<ErasureCodingPolicy> policies;\n    if (root.getElementsByTagName(\"layoutversion\").getLength() > 0) {\n      if (loadLayoutVersion(root) == LAYOUT_VERSION) {\n        if (root.getElementsByTagName(\"schemas\").getLength() > 0) {\n          Map<String, ECSchema> schemas = loadSchemas(root);\n          if (root.getElementsByTagName(\"policies\").getLength() > 0) {\n            policies = loadPolicies(root, schemas);\n          } else {\n            throw new RuntimeException(\"Bad EC policy configuration file: \"\n                + \"no <policies> element\");\n          }\n        } else {\n          throw new RuntimeException(\"Bad EC policy configuration file: \"\n              + \"no <schemas> element\");\n        }","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/util/ECPolicyLoader.java#L81-L117","documentation":"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>'.","triggerScenarios":"`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.","commonSituations":"Users wrapping policies in their own root element; converting from other config formats; copy-paste from documentation that omits the outer element.","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"],"exampleFix":"<!-- before -->\n<policies>\n  <policy>...</policy>\n</policies>\n\n<!-- after -->\n<configuration>\n  <layoutversion>1</layoutversion>\n  <schemas>...</schemas>\n  <policies>\n    <policy>...</policy>\n  </policies>\n</configuration>","handlingStrategy":"validation","validationCode":"Document doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(file);\nif (!\"configuration\".equals(doc.getDocumentElement().getTagName())) {\n  // reject before calling ECPolicyLoader.loadPolicy\n}","typeGuard":null,"tryCatchPattern":"try {\n  new ECPolicyLoader().loadPolicy(path);\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"top-level element not <configuration>\")) {\n    // wrap file contents in a <configuration> root and retry\n  } else { throw e; }\n}","preventionTips":["Always start policy files from the version's shipped template","Automate a structure check (root element + required children) in config CI"],"tags":["hdfs","erasure-coding","ec-policy","xml","schema-validation","configuration"],"backgroundTag":"config-xml-schema-validation","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}