{"record":{"id":"1a28087493076626","repo":"apache/hadoop","slug":"failed-to-load-ec-policy-file-policyfilepath","errorCode":null,"errorMessage":"Failed to load EC policy file: {policyFilePath}","messagePattern":"Failed to load EC policy file: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/util/ECPolicyLoader.java","lineNumber":73,"sourceCode":"      = LoggerFactory.getLogger(ECPolicyLoader.class);\n\n  private static final int LAYOUT_VERSION = 1;\n\n  /**\n   * Load user defined EC policies from a XML configuration file.\n   * @param policyFilePath path of EC policy file\n   * @return all valid EC policies in EC policy file\n   */\n  public List<ErasureCodingPolicy> loadPolicy(String policyFilePath) {\n    try {\n      File policyFile = getPolicyFile(policyFilePath);\n      if (!policyFile.exists()) {\n        LOG.warn(\"Not found any EC policy file\");\n        return Collections.emptyList();\n      }\n      return loadECPolicies(policyFile);\n    } catch (ParserConfigurationException | IOException | SAXException e) {\n      throw new RuntimeException(\"Failed to load EC policy file: \"\n          + policyFilePath);\n    }\n  }\n\n  /**\n   * Load EC policies from a XML configuration file.\n   * @param policyFile EC policy file\n   * @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.","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/util/ECPolicyLoader.java#L55-L91","documentation":"ECPolicyLoader.loadPolicy(path) locates the EC policy XML (a missing file is only a warning returning an empty list) and parses it with a secure DocumentBuilder; the main caller is the `hdfs ec -addPolicies -policyFile` command. Any ParserConfigurationException, IOException or SAXException during the parse is rethrown as a bare RuntimeException 'Failed to load EC policy file: <path>' - the original cause is not attached to the exception, so the message alone tells you little beyond the file path.","triggerScenarios":"Running `hdfs ec -addPolicies -policyFile <path>` (or calling ECPolicyLoader.loadPolicy directly) where the XML is malformed (SAXException), contains a DOCTYPE/DTD the hardened parser rejects, or cannot be read.","commonSituations":"Hand-edited policy files with unclosed tags; files pasted from the web with encoding damage; DOCTYPE declarations forbidden by the secure parser; wrong permissions on the file.","solutions":["Validate syntax first: xmllint --noout <policyFile>","Remove any DOCTYPE/DTD - XMLUtils.newSecureDocumentBuilderFactory rejects doctypes/external entities","Diff against the stock user-ec-policies.xml shipped in etc/hadoop of your distribution and restore the expected structure","If syntax is fine, fix permissions or the path so the process can open the file"],"exampleFix":"<!-- before: malformed (unclosed elements, DOCTYPE) -->\n<!DOCTYPE configuration>\n<configuration>\n  <layoutversion>1</layoutversion>\n  <schemas>...</schemas>\n  <policies><policy><name>RS-10-4-1024k</name></policy>\n\n<!-- after: well-formed, no DOCTYPE -->\n<configuration>\n  <layoutversion>1</layoutversion>\n  <schemas><!-- schema definitions --></schemas>\n  <policies>\n    <policy><name>RS-10-4-1024k</name><!-- schemaId, cellsize... --></policy>\n  </policies>\n</configuration>","handlingStrategy":"validation","validationCode":"// Pre-validate before `hdfs ec -addPolicies`: well-formed XML, no DOCTYPE\nDocumentBuilderFactory dbf = XMLUtils.newSecureDocumentBuilderFactory();\ntry { dbf.newDocumentBuilder().parse(new File(policyFilePath)); }\ncatch (Exception e) { /* reject the file before it reaches the CLI */ }","typeGuard":null,"tryCatchPattern":"try {\n  List<ErasureCodingPolicy> ps = new ECPolicyLoader().loadPolicy(path);\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to load EC policy file\")) {\n    // cause is not chained: run xmllint --noout on the path and fix the XML\n  } else { throw e; }\n}","preventionTips":["Run xmllint --noout on policy files in CI before deploying","Keep files DOCTYPE/DTD-free; the secure parser rejects them","Start from the shipped user-ec-policies.xml template instead of hand-writing XML"],"tags":["hdfs","erasure-coding","ec-policy","xml","hdfs-ec-cli","configuration"],"backgroundTag":"config-xml-parse-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}