apache/hadoop · critical · IOException

Unsupported layout version {}

Error message

Unsupported layout version {}

What it means

After the ondisk-version check, loadSummary() validates the namespace layout version: it must support the PROTOBUF_FORMAT layout feature. A layout version that does not (a pre-protobuf legacy image given to the protobuf loader, or a future layout newer than this build) is rejected. Layout versions only move forward — Hadoop does not support downgrades across layout changes.

Source

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

    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);
    CompressionCodec imageCodec = compression.getImageCodec();
    return imageCodec.createInputStream(in);
  }

}

View on GitHub (pinned to 2add963021)

Solutions

1. Boot with a Hadoop version matching (or newer than) the image's layout version
2. For downgrades, restore the pre-upgrade name dirs saved before the upgrade instead of the new image
3. Recover the namespace on a compatible version, save a fresh image, then plan the version migration properly
4. Snapshot name dirs before every upgrade so rollback uses the right layout

FileSummary s = FSImageUtil.loadSummary(raf);
if (!NameNodeLayoutVersion.supports(
        NameNodeLayoutVersion.Feature.PROTOBUF_FORMAT,
        s.getLayoutVersion())) {
  throw new IOException("layout " + s.getLayoutVersion()
      + " not loadable by this build (downgrade or legacy image)");
}

When it happens

Trigger: Loading an fsimage whose summary layout version predates protobuf images (e.g. a 1.x legacy image) or exceeds the newest layout the running build knows (downgrade attempt after an upgrade wrote a newer layout).

Common situations: Mixing old- and new-format storage directories; downgrading after an upgrade laid down a new layout version; loading an image from a much newer release.

Related errors

• Found feature flags which we can't handle. Please upgrade yo
• BUG: The stored LV = {} is newer than the supported LV = {}
• Unrecognized section {}
• Image file is not found in {}
• No valid image files found

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