apache/hadoop · error · IOException

Expected section header START_ELEMENT; got event of type {}

Error message

Expected section header START_ELEMENT; got event of type {}

What it means

At the top level of <fsimage> the ReverseXML reader accepts only a section START_ELEMENT or the final </fsimage> END_ELEMENT; any other StAX event (characters, comment, DTD, entity reference — the numeric XMLStreamConstants type appears in the message) fails here. OIV-generated XML never has stray non-element nodes between sections, so the input was altered after generation or produced by a non-conforming generator.

Source

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

    final HashSet<String> unprocessedSections =
        new HashSet<>(sections.keySet());
    while (!unprocessedSections.isEmpty()) {
      XMLEvent ev = expectTag("[section header]", true);
      if (ev.getEventType() == XMLStreamConstants.END_ELEMENT) {
        if (ev.asEndElement().getName().getLocalPart().equals("fsimage")) {
          if(unprocessedSections.size() == 1 && unprocessedSections.contains
                  (SnapshotDiffSectionProcessor.NAME)){
            break;
          }
          throw new IOException("FSImage XML ended prematurely, without " +
              "including section(s) " + StringUtils.join(", ",
              unprocessedSections));
        }
        throw new IOException("Got unexpected tag end event for " +
            ev.asEndElement().getName().getLocalPart() + " while looking " +
            "for section header tag.");
      } else if (ev.getEventType() != XMLStreamConstants.START_ELEMENT) {
        throw new IOException("Expected section header START_ELEMENT; " +
            "got event of type " + ev.getEventType());
      }
      String sectionName = ev.asStartElement().getName().getLocalPart();
      if (!unprocessedSections.contains(sectionName)) {
        throw new IOException("Unknown or duplicate section found for " +
            sectionName);
      }
      SectionProcessor sectionProcessor = sections.get(sectionName);
      if (sectionProcessor == null) {
        throw new IOException("Unknown FSImage section " + sectionName +
            ".  Valid section names are [" +
            StringUtils.join(", ", sections.keySet()) + "]");
      }
      unprocessedSections.remove(sectionName);
      sectionProcessor.process();
    }

    // Write the StringTable section to disk.

View on GitHub (pinned to 2add963021)

Solutions

1. Regenerate the XML from the original fsimage with `hdfs oiv -p XML`
2. Strip stray top-level text/comments; decode the event type from javax.xml.stream.XMLStreamConstants (1=START_ELEMENT, 2=END_ELEMENT, 4=CHARACTERS, 5=COMMENT) to know what to hunt for
3. Re-serialize through a standard parser (`xmllint --format` or an XML library) to normalize the document

try {
  int rc = ToolRunner.run(new OfflineImageViewerPB(),
      new String[]{"-p", "ReverseXML", "-i", xmlPath, "-o", outPath});
} catch (Exception e) {
  // the StAX event type is in the message (4=CHARACTERS, 5=COMMENT, ...)
  // stray top-level nodes are an input defect: regenerate, do not retry
  throw new IllegalArgumentException("Invalid OIV XML " + xmlPath + ": " + e.getMessage(), e);
}

When it happens

Trigger: Text pasted directly between section elements, comments or processing instructions at top level, or an XML filter that left character data behind after stripping elements.

Common situations: Annotating OIV XML with notes between sections; sed/awk post-processing that leaves fragments; XML from third-party tools claiming OIV compatibility.

Related errors

• Got unexpected tag end event for {} while looking for sectio
• FSImage XML ended prematurely, without including section(s)
• Unknown or duplicate section found for {}
• Unrecognized FSImage
• no entry found for {}

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