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.

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)

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 {}
• Unexpected HAServiceStateProto:
• Image file is not found in {}
• unknown flags set in ModifyCacheDirectiveInfoOp: {}
• Unknown flag in CachePoolInfo: {}

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