{"record":{"id":"3705d7888d081a25","repo":"apache/hadoop","slug":"unrecognized-fsimage","errorCode":null,"errorMessage":"Unrecognized FSImage","messagePattern":"Unrecognized FSImage","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/FSImageLoader.java","lineNumber":116,"sourceCode":"\n  private FSImageLoader(SerialNumberManager.StringTable stringTable,\n                        byte[][] inodes, Map<Long, long[]> dirmap) {\n    this.stringTable = stringTable;\n    this.inodes = inodes;\n    this.dirmap = dirmap;\n  }\n\n  /**\n   * Load fsimage into the memory.\n   * @param inputFile the filepath of the fsimage to load.\n   * @return FSImageLoader\n   * @throws IOException if failed to load fsimage.\n   */\n  static FSImageLoader load(String inputFile) throws IOException {\n    Configuration conf = new Configuration();\n    RandomAccessFile file = new RandomAccessFile(inputFile, \"r\");\n    if (!FSImageUtil.checkFileFormat(file)) {\n      throw new IOException(\"Unrecognized FSImage\");\n    }\n\n    FsImageProto.FileSummary summary = FSImageUtil.loadSummary(file);\n\n\n    try (FileInputStream fin = new FileInputStream(file.getFD())) {\n      // Map to record INodeReference to the referred id\n      ImmutableList<Long> refIdList = null;\n      SerialNumberManager.StringTable stringTable = null;\n      byte[][] inodes = null;\n      Map<Long, long[]> dirmap = null;\n\n      ArrayList<FsImageProto.FileSummary.Section> sections =\n          Lists.newArrayList(summary.getSectionsList());\n      Collections.sort(sections,\n          new Comparator<FsImageProto.FileSummary.Section>() {\n            @Override\n            public int compare(FsImageProto.FileSummary.Section s1,","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/FSImageLoader.java#L98-L134","documentation":"FSImageLoader.load() validates its input with FSImageUtil.checkFileFormat(): the file must be at least MINIMUM_FILE_LENGTH bytes and start with the 8-byte magic HDFSIMG1. When either check fails it throws IOException(\"Unrecognized FSImage\") — the file is simply not a protobuf-format fsimage. This loader backs the oiv web server and the XML/lsInteractive-style processors.","triggerScenarios":"hdfs oiv (or the -w web server) pointed at an fsimage.md5 checksum sibling, an edit log (edits_inprogress_...), an empty or truncated file, a pre-protobuf Hadoop 1.x fsimage, or any unrelated file.","commonSituations":"Globbing the NameNode storage dir and picking the wrong fsimage_* sibling; images truncated during transfer; running a modern oiv against an old cluster's legacy-format images.","solutions":["Point -i at the fsimage_XXXXXXXXNNNNNNNN file itself — not the .md5, not edits_*.","Verify the header: head -c 8 <file> must print HDFSIMG1.","For Hadoop 1.x images, use hdfs oiv_legacy or produce a protobuf image via a 2.x+ NameNode first.","If the file was copied, compare sizes/checksums with the source to rule out truncation."],"exampleFix":"# before\nhdfs oiv -i /nn/current/fsimage_0000000000000021521.md5 -p XML -o out.xml\n# -> Unrecognized FSImage\n\n# after\nhdfs oiv -i /nn/current/fsimage_0000000000000021521 -p XML -o out.xml","handlingStrategy":"validation","validationCode":"import java.nio.file.*;\n\nstatic boolean isProtoBufFsImage(Path p) throws IOException {\n  if (Files.size(p) < 64) return false;\n  try (InputStream in = Files.newInputStream(p)) {\n    byte[] magic = new byte[8];\n    if (in.read(magic) != 8) return false;\n    return new String(magic, StandardCharsets.UTF_8).equals(\"HDFSIMG1\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  FSImageLoader.load(inputFile);\n} catch (IOException e) {\n  if (\"Unrecognized FSImage\".equals(e.getMessage())) {\n    // wrong or corrupt file: check for .md5, edits_*, truncation, legacy format\n    throw new IOException(\"Not a protobuf fsimage: \" + inputFile, e);\n  }\n  throw e;\n}","preventionTips":["Validate the HDFSIMG1 magic header before running oiv.","Select fsimage_* files explicitly, excluding .md5 and edits_*.","For Hadoop 1.x images use oiv_legacy or upgrade first."],"tags":["hdfs","offline-image-viewer","oiv","fsimage","file-format"],"backgroundTag":"unsupported-file-format","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}