apache/hadoop · error · IllegalArgumentException

Value of <layoutVersion> is null

Error message

Value of <layoutVersion> is null

What it means

ECPolicyLoader.loadLayoutVersion() found the <layoutversion> element but its first child text node is null, meaning the element is empty (<layoutversion/> or <layoutversion></layoutversion>). Thrown as IllegalArgumentException before any parsing is attempted. An element containing only whitespace is not empty — whitespace text is trimmed and would fail as a bad integer instead.

Source

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

  /**
   * Load layoutVersion from root element in the XML configuration file.
   * @param root root element
   * @return layout version
   */
  private int loadLayoutVersion(Element root) {
    int layoutVersion;
    Text text = (Text) root.getElementsByTagName("layoutversion")
        .item(0).getFirstChild();
    if (text != null) {
      String value = text.getData().trim();
      try {
        layoutVersion = Integer.parseInt(value);
      } catch (NumberFormatException e) {
        throw new IllegalArgumentException("Bad layoutVersion value "
            + value + " is found. It should be an integer");
      }
    } else {
      throw new IllegalArgumentException("Value of <layoutVersion> is null");
    }

    return layoutVersion;
  }

  /**
   * Load schemas from root element in the XML configuration file.
   * @param root root element
   * @return EC schema map
   */
  private Map<String, ECSchema> loadSchemas(Element root) {
    NodeList elements = root.getElementsByTagName("schemas")
        .item(0).getChildNodes();
    Map<String, ECSchema> schemas = new HashMap<String, ECSchema>();
    for (int i = 0; i < elements.getLength(); i++) {
      Node node = elements.item(i);
      if (node instanceof Element) {
        Element element = (Element) node;

View on GitHub (pinned to 2add963021)

Solutions

1. Put the value 1 inside the element: <layoutversion>1</layoutversion>
2. If versioning is not intentional, restore the template file from the Hadoop distribution and reapply edits

Example fix

<!-- before -->
<layoutversion/>

<!-- after -->
<layoutversion>1</layoutversion>

Node n = doc.getElementsByTagName("layoutversion").item(0).getFirstChild();
if (n == null || n.getNodeValue().trim().isEmpty()) {
  throw new IllegalArgumentException("<layoutversion> must contain the value 1");
}

try { new ECPolicyLoader().loadPolicy(path); }
catch (IllegalArgumentException e) {
  LOG.error("EC policy file {} rejected: {}", path, e.getMessage());
}

When it happens

Trigger: `hdfs ec -loadPolicy` on a file with an empty <layoutversion/> element, typically left behind when a template value was deleted instead of replaced.

Common situations: Editing user_ec_policies.xml.template and clearing the placeholder text rather than typing 1 into it.

Related errors

• Failed to load EC policy file: {policyFilePath}
• Bad EC policy configuration file: top-level element not <con
• Bad EC policy configuration file: no <layoutVersion> element
• Bad EC policy configuration file: no <policies> element
• Bad EC policy configuration file: no <schemas> element

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