{"record":{"id":"f5e7dbd9a8b36658","repo":"apache/hadoop","slug":"unsupported-layout-version","errorCode":null,"errorMessage":"Unsupported layout version {}","messagePattern":"Unsupported layout version (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImageUtil.java","lineNumber":77,"sourceCode":"\n    if (summaryLength <= 0) {\n      throw new IOException(\"Negative length of the file\");\n    }\n    file.seek(fileLength - FILE_LENGTH_FIELD_SIZE - summaryLength);\n\n    byte[] summaryBytes = new byte[summaryLength];\n    file.readFully(summaryBytes);\n\n    FileSummary summary = FileSummary\n        .parseDelimitedFrom(new ByteArrayInputStream(summaryBytes));\n    if (summary.getOndiskVersion() != FILE_VERSION) {\n      throw new IOException(\"Unsupported file version \"\n          + summary.getOndiskVersion());\n    }\n\n    if (!NameNodeLayoutVersion.supports(Feature.PROTOBUF_FORMAT,\n        summary.getLayoutVersion())) {\n      throw new IOException(\"Unsupported layout version \"\n          + summary.getLayoutVersion());\n    }\n    return summary;\n  }\n\n  public static InputStream wrapInputStreamForCompression(\n      Configuration conf, String codec, InputStream in) throws IOException {\n    if (codec.isEmpty())\n      return in;\n\n    FSImageCompression compression = FSImageCompression.createCompression(\n        conf, codec);\n    CompressionCodec imageCodec = compression.getImageCodec();\n    return imageCodec.createInputStream(in);\n  }\n\n}\n","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImageUtil.java#L59-L95","documentation":"After the ondisk-version check, loadSummary() validates the namespace layout version: it must support the PROTOBUF_FORMAT layout feature. A layout version that does not (a pre-protobuf legacy image given to the protobuf loader, or a future layout newer than this build) is rejected. Layout versions only move forward — Hadoop does not support downgrades across layout changes.","triggerScenarios":"Loading an fsimage whose summary layout version predates protobuf images (e.g. a 1.x legacy image) or exceeds the newest layout the running build knows (downgrade attempt after an upgrade wrote a newer layout).","commonSituations":"Mixing old- and new-format storage directories; downgrading after an upgrade laid down a new layout version; loading an image from a much newer release.","solutions":["Boot with a Hadoop version matching (or newer than) the image's layout version","For downgrades, restore the pre-upgrade name dirs saved before the upgrade instead of the new image","Recover the namespace on a compatible version, save a fresh image, then plan the version migration properly","Snapshot name dirs before every upgrade so rollback uses the right layout"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"FileSummary s = FSImageUtil.loadSummary(raf);\nif (!NameNodeLayoutVersion.supports(\n        NameNodeLayoutVersion.Feature.PROTOBUF_FORMAT,\n        s.getLayoutVersion())) {\n  throw new IOException(\"layout \" + s.getLayoutVersion()\n      + \" not loadable by this build (downgrade or legacy image)\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never downgrade across a layout-version change; roll back to pre-upgrade name dirs instead","Snapshot name dirs immediately before each upgrade","Record the layout version of every archived image so restore tooling picks a compatible release"],"tags":["hadoop","hdfs","namenode","fsimage","layout-version","downgrade"],"backgroundTag":"file-format-version-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}