{"record":{"id":"d28b3676307b5f5f","repo":"apache/hadoop","slug":"file-system-image-contains-an-old-layout-version","errorCode":null,"errorMessage":"\nFile system image contains an old layout version {layoutVersion}.\nAn upgrade to version {serviceLayoutVersion} is required.\nPlease restart NameNode with the \"-rollingUpgrade started\" option if a rolling upgrade is already started; or restart NameNode with the \"-upgrade\" option to start a new upgrade.","messagePattern":"\nFile system image contains an old layout version (.+?)\\.\nAn upgrade to version (.+?) is required\\.\nPlease restart NameNode with the \"-rollingUpgrade started\" option if a rolling upgrade is already started; or restart NameNode with the \"-upgrade\" option to start a new upgrade\\.","errorType":"exception","errorClass":"java.io.IOException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImage.java","lineNumber":274,"sourceCode":"\n\n    int layoutVersion = storage.getLayoutVersion();\n    if (startOpt == StartupOption.METADATAVERSION) {\n      System.out.println(\"HDFS Image Version: \" + layoutVersion);\n      System.out.println(\"Software format version: \" +\n          storage.getServiceLayoutVersion());\n      return false;\n    }\n\n    if (layoutVersion < Storage.LAST_PRE_UPGRADE_LAYOUT_VERSION) {\n      NNStorage.checkVersionUpgradable(storage.getLayoutVersion());\n    }\n    if (startOpt != StartupOption.UPGRADE\n        && startOpt != StartupOption.UPGRADEONLY\n        && !RollingUpgradeStartupOption.STARTED.matches(startOpt)\n        && layoutVersion < Storage.LAST_PRE_UPGRADE_LAYOUT_VERSION\n        && layoutVersion != storage.getServiceLayoutVersion()) {\n      throw new IOException(\n          \"\\nFile system image contains an old layout version \" \n          + storage.getLayoutVersion() + \".\\nAn upgrade to version \"\n          + storage.getServiceLayoutVersion() + \" is required.\\n\"\n          + \"Please restart NameNode with the \\\"\"\n          + RollingUpgradeStartupOption.STARTED.getOptionString()\n          + \"\\\" option if a rolling upgrade is already started;\"\n          + \" or restart NameNode with the \\\"\"\n          + StartupOption.UPGRADE.getName() + \"\\\" option to start\"\n          + \" a new upgrade.\");\n    }\n    \n    storage.processStartupOptionsForUpgrade(startOpt, layoutVersion);\n\n    // 2. Format unformatted dirs.\n    for (Iterator<StorageDirectory> it = storage.dirIterator(); it.hasNext();) {\n      StorageDirectory sd = it.next();\n      StorageState curState = dataDirStates.get(sd);\n      switch(curState) {","sourceCodeStart":256,"sourceCodeEnd":292,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImage.java#L256-L292","documentation":"The on-disk fsimage layout version is older than the software's layout and older than Storage.LAST_PRE_UPGRADE_LAYOUT_VERSION-era rules permit for plain reading, while the startup option is not -upgrade/-upgradeOnly/-rollingUpgrade started. Hadoop forbids new binaries from silently adopting old metadata: moving the namespace to the new layout requires an explicit upgrade.","triggerScenarios":"Starting the NameNode normally after installing a newer Hadoop release over metadata formatted by an older release; resuming after a rolling upgrade was initiated elsewhere without passing -rollingUpgrade started; metadata volumes moved from an old cluster to new binaries.","commonSituations":"Upgrade runbook skips the -upgrade step; interrupted rolling upgrade resumed with a plain start; test clusters reusing old data dirs with new Hadoop tarballs.","solutions":["If you intend to upgrade, restart with 'hdfs --daemon start namenode -upgrade' (then finalize later with 'hdfs dfsadmin -finalizeUpgrade').","If a rolling upgrade was already started on other nodes, restart with 'hdfs --daemon start namenode -rollingUpgrade started'.","If you did not intend to upgrade, run the previous Hadoop release binaries against this metadata.","If the metadata is older than the upgradable range, upgrade stepwise through intermediate releases (checkVersionUpgradable enforces that separately)."],"exampleFix":"# before\nhdfs --daemon start namenode\n# IOException: File system image contains an old layout version ...\n\n# after\nhdfs --daemon start namenode -upgrade\n# or, for an in-progress rolling upgrade:\nhdfs --daemon start namenode -rollingUpgrade started","handlingStrategy":"validation","validationCode":"Properties props = new Properties();\ntry (InputStream is = Files.newInputStream(\n        Paths.get(nameDir, \"current\", \"VERSION\"))) {\n  props.load(is);\n}\nint lv = Integer.parseInt(props.getProperty(\"layoutVersion\"));\nint svc = HdfsServerConstants.NAMENODE_LAYOUT_VERSION;\nif (lv != svc) {\n  // decide before starting: -upgrade, -rollingUpgrade started, or old binaries\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Bake the '-upgrade' flag step into the release rollout runbook.","Record layoutVersion before and after every upgrade.","During rolling upgrades, always resume with '-rollingUpgrade started' until finalized."],"tags":["hdfs","namenode","upgrade","layout-version","startup"],"backgroundTag":"layout-version-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}