apache/hadoop · error · IOException

Found unknown XML keys in {sectionName}: {remainingKeyNames}

Error message

Found unknown XML keys in {sectionName}: {remainingKeyNames}

What it means

Each SectionProcessor removes the elements it understands from the parsed Node tree, then verifyNoRemainingKeys fails if anything is left (the leftover key names are joined into the message). This is the reconstructor's schema check: the section contains elements this oiv version does not recognize - misspelled, manually added, or belonging to another Hadoop version's XML dialect.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/OfflineImageReconstructor.java:327

    boolean removeChildBool(String key) throws IOException {
      String str = removeChildStr(key);
      if (str == null) {
        return false;
      }
      return true;
    }

    String getRemainingKeyNames() {
      if (children == null) {
        return "";
      }
      return StringUtils.join(", ", children.keySet());
    }

    void verifyNoRemainingKeys(String sectionName) throws IOException {
      String remainingKeyNames = getRemainingKeyNames();
      if (!remainingKeyNames.isEmpty()) {
        throw new IOException("Found unknown XML keys in " +
            sectionName + ": " + remainingKeyNames);
      }
    }

    void setVal(String val) {
      this.val = val;
    }

    String getVal() {
      return val;
    }

    String dump() {
      StringBuilder bld = new StringBuilder();
      if ((children != null) && (!children.isEmpty())) {
        bld.append("{");
      }
      if (val != null) {

View on GitHub (pinned to 2add963021)

Solutions

1. Remove or correct every key listed in the message - it enumerates all leftovers for the section
2. Regenerate the XML with the same Hadoop version that will run ReverseXML
3. If the fields are genuinely needed, move to a Hadoop version whose fsimage schema includes them; unknown keys are rejected by design

Example fix

<!-- before: misspelled field name -->
<NameSection><namespaceId>1</namespaceId><genstampV2Stampe>1000</genstampV2Stampe></NameSection>

<!-- after -->
<NameSection><namespaceId>1</namespaceId><genstampV2>1000</genstampV2></NameSection>

# Every element of each section must be a key this oiv version consumes;
# cheapest proxy: compare against a freshly generated dump of the same image
hdfs oiv -p XML -i fsimage_orig -o reference.xml
for s in NameSection INodeSection; do
  diff <(xmllint --xpath "//$s/*[name()]" reference.xml | tr '>' '>
' | cut -d'<' -f2 | cut -d' ' -f1 | sort -u) \
       <(xmllint --xpath "//$s/*[name()]" fsimage.xml  | tr '>' '>
' | cut -d'<' -f2 | cut -d' ' -f1 | sort -u) \
    || { echo "unknown/missing keys in <$s>"; exit 1; }
done

When it happens

Trigger: Typos in tag names (e.g. <genstampV2Stampe>), hand-added fields in the hope they get persisted, or XML generated by a different oiv version containing extra/renamed fields that this version's processor never removes.

Common situations: Editing XML to inject settings or new metadata; feeding a newer Hadoop dump into an older ReverseXML.

Related errors

• Expecting {expected}, but got XMLStreamException
• Got unexpected attribute: {ev}
• Got unxpected characters while looking for {expected}: {ev.a
• Got unexpected end event while looking for {expected}
• Failed to find <{expected}>; got {ev.asStartElement().getNam

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