apache/hadoop · critical · IOException

Unsupported file version

Error message

Unsupported file version {}

What it means

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.

Solutions

1. Upgrade the reading software to the Hadoop release that wrote the image
2. Confirm you are loading a real protobuf fsimage (check the file was produced by a NameNode checkpoint)
3. If you deliberately downgraded, roll back to the pre-upgrade storage directories instead of reading the new-format image
4. If only the content matters, dump it with OfflineImageViewer of the appropriate version

FileSummary s = FSImageUtil.loadSummary(raf);
if (s.getOndiskVersion() != FSImageUtil.FILE_VERSION) { // FILE_VERSION == 1
  throw new IOException("unsupported fsimage format revision "
      + s.getOndiskVersion() + " - use a matching Hadoop release");
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unrecognized section
• Image file is not found in
• Negative length of the file
• No valid image files found
• Unexpected HAServiceStateProto:

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/85a4437d880cbdcc. Report an issue: GitHub.

Appendix: source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImageUtil.java:71

  public static FileSummary loadSummary(RandomAccessFile file)
      throws IOException {
    final int FILE_LENGTH_FIELD_SIZE = 4;
    long fileLength = file.length();
    file.seek(fileLength - FILE_LENGTH_FIELD_SIZE);
    int summaryLength = file.readInt();

    if (summaryLength <= 0) {
      throw new IOException("Negative length of the file");
    }
    file.seek(fileLength - FILE_LENGTH_FIELD_SIZE - summaryLength);

    byte[] summaryBytes = new byte[summaryLength];
    file.readFully(summaryBytes);

    FileSummary summary = FileSummary
        .parseDelimitedFrom(new ByteArrayInputStream(summaryBytes));
    if (summary.getOndiskVersion() != FILE_VERSION) {
      throw new IOException("Unsupported file version "
          + summary.getOndiskVersion());
    }

    if (!NameNodeLayoutVersion.supports(Feature.PROTOBUF_FORMAT,
        summary.getLayoutVersion())) {
      throw new IOException("Unsupported layout version "
          + summary.getLayoutVersion());
    }
    return summary;
  }

  public static InputStream wrapInputStreamForCompression(
      Configuration conf, String codec, InputStream in) throws IOException {
    if (codec.isEmpty())
      return in;

    FSImageCompression compression = FSImageCompression.createCompression(
        conf, codec);

View on GitHub (pinned to 2add963021)