{"record":{"id":"bbecf2834d64a92c","repo":"apache/hadoop","slug":"no-version-section-found-at-the-top-of-the-fsima","errorCode":null,"errorMessage":"No <version> section found at the top of the fsimage XML.  This XML file is too old to be processed by oiv.","messagePattern":"No <version> section found at the top of the fsimage XML\\.  This XML file is too old to be processed by oiv\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/OfflineImageReconstructor.java","lineNumber":1684,"sourceCode":"          setName(sectionNamePb).\n          setLength(curPos - curSectionStartOffset).\n          setOffset(curSectionStartOffset));\n    //}\n    sectionStartOffset = curPos;\n  }\n\n  /**\n   * Read the version tag which starts the XML file.\n   */\n  private void readVersion() throws IOException {\n    try {\n      expectTag(\"version\", false);\n    } catch (IOException e) {\n      // Handle the case where <version> does not exist.\n      // Note: fsimage XML files which are missing <version> are also missing\n      // many other fields that oiv needs to accurately reconstruct the\n      // fsimage.\n      throw new IOException(\"No <version> section found at the top of \" +\n          \"the fsimage XML.  This XML file is too old to be processed \" +\n          \"by oiv.\", e);\n    }\n    Node version = new Node();\n    loadNodeChildren(version, \"version fields\");\n    Integer onDiskVersion = version.removeChildInt(\"onDiskVersion\");\n    if (onDiskVersion == null) {\n      throw new IOException(\"The <version> section doesn't contain \" +\n          \"the onDiskVersion.\");\n    }\n    Integer layoutVersion = version.removeChildInt(\"layoutVersion\");\n    if (layoutVersion == null) {\n      throw new IOException(\"The <version> section doesn't contain \" +\n          \"the layoutVersion.\");\n    }\n    if (layoutVersion.intValue() !=\n        NameNodeLayoutVersion.CURRENT_LAYOUT_VERSION) {\n      throw new IOException(\"Layout version mismatch.  This oiv tool \" +","sourceCodeStart":1666,"sourceCodeEnd":1702,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/OfflineImageReconstructor.java#L1666-L1702","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Confirm the `-i` file really is an fsimage XML dump (starts with <fsimage><version>) and not another XML file","If only the old XML exists, reconstruct with the old Hadoop version's oiv first, then roll the resulting image forward via NameNode upgrade","Keep binary fsimages alongside XML exports so dumps can always be regenerated"],"exampleFix":"<!-- before: dump starts directly with a section -->\n<fsimage><NameSection>...</NameSection>...</fsimage>\n<!-- after: version header present (regenerate with a current oiv) -->\n<fsimage><version><onDiskVersion>1</onDiskVersion><layoutVersion>-66</layoutVersion></version><NameSection>...</NameSection>...</fsimage>","handlingStrategy":"validation","validationCode":"# python: dump must open with <fsimage><version>\nimport xml.etree.ElementTree as ET\n\ndef has_version_section(path):\n    for ev, el in ET.iterparse(path, events=('start',)):\n        return el.tag == 'fsimage' or el.tag == 'version'\n    return False\n\ndef first_element(path):\n    it = ET.iterparse(path, events=('start',))\n    _, root = next(it)\n    return root.tag  # must be 'fsimage'; its first child must be 'version'","typeGuard":"def is_reconstructable_xml(path) -> bool:\n    \"\"\"True if the dump starts with <fsimage> and a <version> child.\"\"\"\n    it = ET.iterparse(path, events=('start',))\n    _, root = next(it)\n    if root.tag != 'fsimage':\n        return False\n    _, first = next(it)\n    return first.tag == 'version'","tryCatchPattern":"# detect the 'too old' failure, then regenerate the XML with a current\n# oiv from the original binary fsimage before retrying","preventionTips":["Archive binary fsimages alongside XML exports","Regenerate XML with the same oiv version used for reconstruction","Check the file starts with <fsimage><version> before running ReverseXML","Never feed arbitrary XML files to `-i`"],"tags":["hdfs","oiv","fsimage","reversexml","version","legacy-format"],"backgroundTag":"fsimage-xml-version-header-missing","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}