apache/hadoop · error · IOException

Layout version mismatch. This oiv tool handles layout versi

Error message

Layout version mismatch.  This oiv tool handles layout version {}, but the XML file has <layoutVersion> {}.  Please either re-generate the XML file with the proper layout version, or manually edit the XML file to be usable with this version of the oiv tool.

What it means

The <version> block's <layoutVersion> does not equal NameNodeLayoutVersion.CURRENT_LAYOUT_VERSION of the oiv build doing the reconstruction. ReverseXML deliberately supports only the exact layout it was compiled for - one layout version means one on-disk protobuf schema - so cross-version reconstruction is rejected outright rather than producing a subtly corrupt image.

Source

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

      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 " +
          "handles layout version " +
          NameNodeLayoutVersion.CURRENT_LAYOUT_VERSION + ", but the " +
          "XML file has <layoutVersion> " + layoutVersion + ".  Please " +
          "either re-generate the XML file with the proper layout version, " +
          "or manually edit the XML file to be usable with this version " +
          "of the oiv tool.");
    }
    fileSummaryBld.setOndiskVersion(onDiskVersion);
    fileSummaryBld.setLayoutVersion(layoutVersion);
    if (LOG.isDebugEnabled()) {
      LOG.debug("Loaded <version> with onDiskVersion=" + onDiskVersion +
          ", layoutVersion=" + layoutVersion + ".");
    }
  }

  /**
   * Write the string table to the fsimage.
   * @throws IOException

View on GitHub (pinned to 2add963021)

Solutions

1. Regenerate the XML with the same Hadoop build you will reconstruct with (`hdfs oiv -processor XML`), then run ReverseXML in that same build
2. Alternatively run ReverseXML with the Hadoop version whose layout matches the XML, then roll the image forward via a NameNode layout upgrade
3. Check the error message: it names both the expected and actual layout versions - make them agree
4. Pin the Hadoop version in recovery runbooks so dump and reconstruct steps never drift

Example fix

# before: dump and reconstruct with different releases
hdfs-oiv-2.8 -i fsimage_0001 -o dump.xml   # layoutVersion -60
hdfs-oiv-3.3 -processor ReverseXML -i dump.xml -o fixed.img  # expects -66 -> fails
# after: same release for both steps
hdfs-oiv-3.3 -i fsimage_0001 -o dump.xml
hdfs-oiv-3.3 -processor ReverseXML -i dump.xml -o fixed.img

# python: layoutVersion in the XML must equal the oiv build's current layout
import subprocess, xml.etree.ElementTree as ET

def layout_matches(path, current_lv):
    for ev, el in ET.iterparse(path, events=('end',)):
        if el.tag == 'layoutVersion':
            return int(el.text) == current_lv
    return False
# obtain current_lv from the same Hadoop build, e.g.:
#   hdfs oiv -processor XML -i fsimage_0001 -o probe.xml  (regenerate instead)

def is_layout_compatible(xml_lv: int, oiv_current_lv: int) -> bool:
    """True only when the dump's layout equals the reconstructing oiv's layout."""
    return xml_lv == oiv_current_lv

# catch the mismatch message (it prints both versions); regenerate the XML
# with the same Hadoop build, or switch the reconstructing oiv to that build

When it happens

Trigger: Dumping XML with one Hadoop release's oiv and reconstructing with another (e.g. dump on 2.x, `hdfs oiv -processor ReverseXML` on 3.x), or hand-editing <layoutVersion> to a value the running oiv does not implement.

Common situations: Cluster upgrades between dump and restore; shared XML fixtures reused across Hadoop versions in CI; disaster recovery where the recovery host runs a different Hadoop release than the archived image.

Related errors

• Cannot process fslayout version {imageVersion}
• Only read ${actualNumSnapshots} <snapshot> entries out of ${
• <snapshot> section was missing <id>
• Got unexpected end tag for ${name}
• SnapshotDiffSection contained unexpected tag ${tagName}

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