apache/hadoop · error · IOException

No <version> section found at the top of the fsimage XML. T

Error message

No <version> section found at the top of the fsimage XML.  This XML file is too old to be processed by oiv.

What it means

The very first thing the reconstructor does is expect a <version> element at the top of the XML; expectTag("version") threw, meaning the dump does not start with a <version> section. As the code comment notes, XML missing <version> is also missing many other fields oiv needs, so the file is treated as too old to process at all.

Source

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

          setName(sectionNamePb).
          setLength(curPos - curSectionStartOffset).
          setOffset(curSectionStartOffset));
    //}
    sectionStartOffset = curPos;
  }

  /**
   * Read the version tag which starts the XML file.
   */
  private void readVersion() throws IOException {
    try {
      expectTag("version", false);
    } catch (IOException e) {
      // Handle the case where <version> does not exist.
      // Note: fsimage XML files which are missing <version> are also missing
      // many other fields that oiv needs to accurately reconstruct the
      // fsimage.
      throw new IOException("No <version> section found at the top of " +
          "the fsimage XML.  This XML file is too old to be processed " +
          "by oiv.", e);
    }
    Node version = new Node();
    loadNodeChildren(version, "version fields");
    Integer onDiskVersion = version.removeChildInt("onDiskVersion");
    if (onDiskVersion == null) {
      throw new IOException("The <version> section doesn't contain " +
          "the onDiskVersion.");
    }
    Integer layoutVersion = version.removeChildInt("layoutVersion");
    if (layoutVersion == null) {
      throw new IOException("The <version> section doesn't contain " +
          "the layoutVersion.");
    }
    if (layoutVersion.intValue() !=
        NameNodeLayoutVersion.CURRENT_LAYOUT_VERSION) {
      throw new IOException("Layout version mismatch.  This oiv tool " +

View on GitHub (pinned to 2add963021)

Solutions

1. Regenerate the XML with a current oiv (`hdfs oiv -processor XML -i fsimage_XXXX`) from the original binary fsimage - old XML cannot be upgraded in place
2. Confirm the `-i` file really is an fsimage XML dump (starts with <fsimage><version>) and not another XML file
3. If only the old XML exists, reconstruct with the old Hadoop version's oiv first, then roll the resulting image forward via NameNode upgrade
4. Keep binary fsimages alongside XML exports so dumps can always be regenerated

Example fix

<!-- before: dump starts directly with a section -->
<fsimage><NameSection>...</NameSection>...</fsimage>
<!-- after: version header present (regenerate with a current oiv) -->
<fsimage><version><onDiskVersion>1</onDiskVersion><layoutVersion>-66</layoutVersion></version><NameSection>...</NameSection>...</fsimage>

# python: dump must open with <fsimage><version>
import xml.etree.ElementTree as ET

def has_version_section(path):
    for ev, el in ET.iterparse(path, events=('start',)):
        return el.tag == 'fsimage' or el.tag == 'version'
    return False

def first_element(path):
    it = ET.iterparse(path, events=('start',))
    _, root = next(it)
    return root.tag  # must be 'fsimage'; its first child must be 'version'

def is_reconstructable_xml(path) -> bool:
    """True if the dump starts with <fsimage> and a <version> child."""
    it = ET.iterparse(path, events=('start',))
    _, root = next(it)
    if root.tag != 'fsimage':
        return False
    _, first = next(it)
    return first.tag == 'version'

# detect the 'too old' failure, then regenerate the XML with a current
# oiv from the original binary fsimage before retrying

When it happens

Trigger: Feeding ReverseXML an XML dump produced by an old oiv from before the <version> section existed, a hand-authored file that never had it, or a non-fsimage XML file passed to `-i` by mistake.

Common situations: Using a modern `hdfs oiv -processor ReverseXML` against XML exported years ago by an old cluster's oiv; passing a generic XML config/data file instead of an fsimage dump; rebuilding disaster-recovery images archived in the old format.

Related errors

• The <version> section doesn't contain the onDiskVersion.
• The <version> section doesn't contain the layoutVersion.
• Only read ${actualNumSnapshots} <snapshot> entries out of ${
• <snapshot> section was missing <id>
• Got unexpected end tag for ${name}

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