{"record":{"id":"6f2d75034c4b474f","repo":"apache/hadoop","slug":"unrecognized-fsimage-6f2d75","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/PBImageTextWriter.java","lineNumber":597,"sourceCode":"\n  /**\n   * Get text output for the header line.\n   */\n  abstract protected String getHeader();\n\n  /**\n   * Method called at the end of output() phase after all the inodes\n   * with known parentPath has been printed out. Can be used to print\n   * additional data depending on the written inodes.\n   */\n  abstract protected void afterOutput() throws IOException;\n\n  public void visit(String filePath) throws IOException {\n    filename = new File(filePath);\n    RandomAccessFile file = new RandomAccessFile(filePath, \"r\");\n    Configuration conf = new Configuration();\n    if (!FSImageUtil.checkFileFormat(file)) {\n      throw new IOException(\"Unrecognized FSImage\");\n    }\n\n    FileSummary summary = FSImageUtil.loadSummary(file);\n\n    try (FileInputStream fin = new FileInputStream(file.getFD())) {\n      InputStream is;\n      ArrayList<FileSummary.Section> sections =\n          Lists.newArrayList(summary.getSectionsList());\n      Collections.sort(sections,\n          new Comparator<FileSummary.Section>() {\n            @Override\n            public int compare(FsImageProto.FileSummary.Section s1,\n                FsImageProto.FileSummary.Section s2) {\n              FSImageFormatProtobuf.SectionName n1 =\n                  FSImageFormatProtobuf.SectionName.fromString(s1.getName());\n              FSImageFormatProtobuf.SectionName n2 =\n                  FSImageFormatProtobuf.SectionName.fromString(s2.getName());\n              if (n1 == null) {","sourceCodeStart":579,"sourceCodeEnd":615,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/PBImageTextWriter.java#L579-L615","documentation":"Before parsing, PBImageTextWriter.visit() (the Delimited/DetectCorruption processors of `hdfs oiv`) verifies via FSImageUtil.checkFileFormat that the file starts with the fsimage magic 'HDFSIMG1' and meets the minimum length. The check failed, so the input is not a protobuf fsimage: it may be an edit log, the .md5 sidecar, a legacy pre-2.x image, a truncated download, or an unrelated file.","triggerScenarios":"Passing edits_inprogress_*, fsimage.md5, a legacy-format image, or a partially downloaded fsimage to `hdfs oiv -i`; globbing /dfs/name/current/* and feeding the wrong match.","commonSituations":"Shell glob picking an edits file instead of the image; an interrupted download leaving a short file; an HTML error page saved as the 'image'; legacy image run through the PB tool.","solutions":["Confirm the target is a protobuf fsimage: `head -c 8 <file>` must print HDFSIMG1","Pick the file explicitly by name (fsimage_<txid>, largest txid = newest) instead of globbing","Verify the transfer with the sibling fsimage.md5 (`md5sum -c`); re-download on mismatch","For pre-Hadoop-2 images use `hdfs oiv_legacy`"],"exampleFix":"# before: wrong file from a glob\nhdfs oiv -p delimited -i /dfs/name/current/edits_* -o out.csv\n# IOException: Unrecognized FSImage\n\n# after: select and verify the real image first\nhead -c 8 /dfs/name/current/fsimage_0000000000000123456   # HDFSIMG1\nhdfs oiv -p delimited -i /dfs/name/current/fsimage_0000000000000123456 -o out.csv","handlingStrategy":"validation","validationCode":"// Reject non-fsimage input before calling visit()\ntry (RandomAccessFile f = new RandomAccessFile(path, \"r\")) {\n  byte[] magic = new byte[FSImageUtil.MAGIC_HEADER.length];\n  f.readFully(magic);\n  if (!Arrays.equals(magic, FSImageUtil.MAGIC_HEADER)) {\n    throw new IllegalArgumentException(\n        path + \" is not a protobuf fsimage (missing HDFSIMG1 magic)\");\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Select the input by explicit fsimage_<txid> name, never by glob over current/","Verify md5 against the fsimage.md5 sidecar after any transfer","Remember edits logs and fsimage.md5 never pass the magic check by design"],"tags":["hdfs","offline-image-viewer","fsimage","file-format"],"backgroundTag":"invalid-file-format","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}