{"record":{"id":"ec754c6276df8485","repo":"apache/hadoop","slug":"cannot-process-fslayout-version-imageversion","errorCode":null,"errorMessage":"Cannot process fslayout version {imageVersion}","messagePattern":"Cannot process fslayout version (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/ImageLoaderCurrent.java","lineNumber":161,"sourceCode":"      if(v == version) return true;\n\n    return false;\n  }\n\n  /* (non-Javadoc)\n   * @see ImageLoader#processImage(java.io.DataInputStream, ImageVisitor, boolean)\n   */\n  @Override\n  public void loadImage(DataInputStream in, ImageVisitor v,\n      boolean skipBlocks) throws IOException {\n    boolean done = false;\n    try {\n      v.start();\n      v.visitEnclosingElement(ImageElement.FS_IMAGE);\n\n      imageVersion = in.readInt();\n      if( !canLoadVersion(imageVersion))\n        throw new IOException(\"Cannot process fslayout version \" + imageVersion);\n      if (NameNodeLayoutVersion.supports(Feature.ADD_LAYOUT_FLAGS, imageVersion)) {\n        LayoutFlags.read(in);\n      }\n\n      v.visit(ImageElement.IMAGE_VERSION, imageVersion);\n      v.visit(ImageElement.NAMESPACE_ID, in.readInt());\n\n      long numInodes = in.readLong();\n\n      v.visit(ImageElement.GENERATION_STAMP, in.readLong());\n\n      if (NameNodeLayoutVersion.supports(Feature.SEQUENTIAL_BLOCK_ID, imageVersion)) {\n        v.visit(ImageElement.GENERATION_STAMP_V2, in.readLong());\n        v.visit(ImageElement.GENERATION_STAMP_V1_LIMIT, in.readLong());\n        v.visit(ImageElement.LAST_ALLOCATED_BLOCK_ID, in.readLong());\n      }\n\n      if (NameNodeLayoutVersion.supports(Feature.STORED_TXIDS, imageVersion)) {","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/ImageLoaderCurrent.java#L143-L179","documentation":"ImageLoaderCurrent is the legacy (pre-protobuf) fsimage reader behind `hdfs oiv_legacy`. loadImage reads the first int of the image and calls canLoadVersion, which accepts exactly the layout versions listed in the array at ImageLoaderCurrent.java:129-131 (-16 through -51). Any other value - a protobuf-era image (-52 and newer) or a pre-0.18 image - aborts with this IOException because the reader has no parsing rules for that layout.","triggerScenarios":"`hdfs oiv_legacy -p Indented -i fsimage_XXX -o out` on an fsimage written by a Hadoop 2.x/3.x NameNode (protobuf layout, e.g. -66), by a release newer than the tool, or older than layout -16; also calling ImageLoader.loadImage / ImageLoaderCurrent.loadImage directly on such a file.","commonSituations":"Mixing Hadoop distro versions (old oiv binary pointed at a new cluster's image); legacy monitoring scripts still invoking oiv_legacy after a cluster upgrade to 2.x+; admins unaware that modern fsimages must go through the protobuf-based `hdfs oiv`.","solutions":["Use the modern protobuf tool: `hdfs oiv -p XML|Indented|Delimited -i <fsimage> -o <out>`","Run the oiv binary from the same Hadoop release (or newer) as the NameNode that wrote the fsimage","Confirm the image format first (first 4 bytes of the file are the layout version; protobuf images also fail oiv_legacy immediately) and pick the matching tool","Reserve oiv_legacy strictly for genuine Hadoop 0.20/1.x images with layout -16..-51"],"exampleFix":"# before\nhdfs oiv_legacy -p Indented -i fsimage_0000000000000060000 -o out.txt\n# IOException: Cannot process fslayout version -66\n\n# after\nhdfs oiv -p Indented -i fsimage_0000000000000060000 -o out.txt","handlingStrategy":"validation","validationCode":"// Peek the layout version before handing the file to the legacy loader\ntry (DataInputStream in = new DataInputStream(\n        new BufferedInputStream(new FileInputStream(fsImagePath)))) {\n  int layoutVersion = in.readInt(); // first field of an fsimage\n  if (layoutVersion > -16 || layoutVersion < -51) {\n    throw new IllegalArgumentException(\n        \"oiv_legacy supports layout -16..-51; this image is \" + layoutVersion\n        + \" - use the protobuf `hdfs oiv` from the matching Hadoop release\");\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Standardize on `hdfs oiv` (protobuf loader) for every Hadoop 2.x+ cluster","Match the oiv binary's Hadoop version to the NameNode that wrote the image","Record which archived images are pre-protobuf and pin those to oiv_legacy"],"tags":["hdfs","fsimage","layout-version","version-mismatch","offline-image-viewer"],"backgroundTag":"unsupported-file-version","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}