{"record":{"id":"5a54ac66c64812ef","repo":"apache/hadoop","slug":"bad-ec-policy-configuration-file-no-layoutversio","errorCode":null,"errorMessage":"Bad EC policy configuration file: no <layoutVersion> element","messagePattern":"Bad EC policy configuration file: no <layoutVersion> element","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":123,"sourceCode":"      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        }\n      } else {\n        throw new RuntimeException(\"The parse failed because of \"\n            + \"bad layoutversion value\");\n      }\n    } else {\n      throw new RuntimeException(\"Bad EC policy configuration file: \"\n          + \"no <layoutVersion> element\");\n    }\n\n    return policies;\n  }\n\n  /**\n   * Load layoutVersion from root element in the XML configuration file.\n   * @param root root element\n   * @return layout version\n   */\n  private int loadLayoutVersion(Element root) {\n    int layoutVersion;\n    Text text = (Text) root.getElementsByTagName(\"layoutversion\")\n        .item(0).getFirstChild();\n    if (text != null) {\n      String value = text.getData().trim();\n      try {","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/util/ECPolicyLoader.java#L105-L141","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add <layoutversion>1</layoutversion> (lowercase tag, integer value 1) as a direct child of <configuration>","Start from the shipped user_ec_policies.xml.template and edit only the <schema>/<policy> entries","Validate before loading: xmllint --xpath 'count(/configuration/layoutversion)' file.xml must return 1","Confirm the root element is exactly <configuration>; other roots are rejected earlier with a different message"],"exampleFix":"<!-- before -->\n<configuration>\n  <schemas>...</schemas>\n</configuration>\n\n<!-- after -->\n<configuration>\n  <layoutversion>1</layoutversion>\n  <schemas>...</schemas>\n</configuration>","handlingStrategy":"validation","validationCode":"Document doc = XMLUtils.newSecureDocumentBuilderFactory().newDocumentBuilder()\n    .parse(new File(policyFilePath));\nif (!\"configuration\".equals(doc.getDocumentElement().getTagName())\n    || doc.getElementsByTagName(\"layoutversion\").getLength() == 0) {\n  throw new IllegalArgumentException(\n      policyFilePath + \" lacks <layoutversion> under <configuration>; fix before loadPolicy()\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  List<ErasureCodingPolicy> ps = new ECPolicyLoader().loadPolicy(path);\n} catch (RuntimeException e) {\n  // message names the structural defect; include the file path in operator output\n  LOG.error(\"EC policy file {} rejected: {}\", path, e.getMessage());\n}","preventionTips":["Author policy files from user_ec_policies.xml.template, never from scratch","Keep tags lowercase — the DOM lookup for layoutversion is case-sensitive","Run xmllint over the file in CI before `hdfs ec -loadPolicy`"],"tags":["hdfs","erasure-coding","ec-policy","xml","configuration"],"backgroundTag":"xml-config-missing-element","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}