{"record":{"id":"85a4437d880cbdcc","repo":"apache/hadoop","slug":"unsupported-file-version","errorCode":null,"errorMessage":"Unsupported file version {}","messagePattern":"Unsupported file 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":71,"sourceCode":"  public static FileSummary loadSummary(RandomAccessFile file)\n      throws IOException {\n    final int FILE_LENGTH_FIELD_SIZE = 4;\n    long fileLength = file.length();\n    file.seek(fileLength - FILE_LENGTH_FIELD_SIZE);\n    int summaryLength = file.readInt();\n\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);","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImageUtil.java#L53-L89","documentation":"The protobuf fsimage FileSummary carries an ondiskVersion field — the file-format revision, distinct from the namespace layout version. FSImageUtil.loadSummary() only accepts FSImageUtil.FILE_VERSION (1); any other value throws. Seeing it means the file is a different on-disk format generation: typically a future format read by older binaries, or the file is not an fsimage at all.","triggerScenarios":"Loading an fsimage whose summary.getOndiskVersion() != 1: produced by a newer on-disk format revision, or the loader pointed at a random/truncated file whose tail parses to a different version.","commonSituations":"Reading images across major-version boundaries that changed the format; passing a non-fsimage file to the loader; copy truncated in a way that shifts the tail.","solutions":["Upgrade the reading software to the Hadoop release that wrote the image","Confirm you are loading a real protobuf fsimage (check the file was produced by a NameNode checkpoint)","If you deliberately downgraded, roll back to the pre-upgrade storage directories instead of reading the new-format image","If only the content matters, dump it with OfflineImageViewer of the appropriate version"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"FileSummary s = FSImageUtil.loadSummary(raf);\nif (s.getOndiskVersion() != FSImageUtil.FILE_VERSION) { // FILE_VERSION == 1\n  throw new IOException(\"unsupported fsimage format revision \"\n      + s.getOndiskVersion() + \" - use a matching Hadoop release\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check the Hadoop release that wrote an image before moving it across clusters","Keep a version map of which binaries produced each archived image","Never point tooling at a file that was not produced as a NameNode checkpoint"],"tags":["hadoop","hdfs","namenode","fsimage","protobuf","version-mismatch"],"backgroundTag":"file-format-version-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}