apache/hadoop · critical · IOException

Unrecognized section {}

Error message

Unrecognized section {}

What it means

FSImageFormatProtobuf.Loader walks the FileSummary section list at the tail of a protobuf-format fsimage and maps each section name to the SectionName enum via SectionName.fromString(). A section name that maps to no enum constant aborts loading with IOException("Unrecognized section ..."), meaning the image contains section types this Hadoop build cannot parse. Almost always this is version skew (image written by a newer/older release) or byte-level corruption of the summary block.

Source

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

      ExecutorService executorService = null;
      ArrayList<FileSummary.Section> subSections =
          getAndRemoveSubSections(sections);
      if (loadInParallel) {
        executorService = getParallelExecutorService();
      }

      for (FileSummary.Section s : sections) {
        channel.position(s.getOffset());
        InputStream in = new BufferedInputStream(new LimitInputStream(fin,
            s.getLength()));

        in = FSImageUtil.wrapInputStreamForCompression(conf,
            summary.getCodec(), in);

        String n = s.getName();
        SectionName sectionName = SectionName.fromString(n);
        if (sectionName == null) {
          throw new IOException("Unrecognized section " + n);
        }

        ArrayList<FileSummary.Section> stageSubSections;
        switch (sectionName) {
        case NS_INFO:
          loadNameSystemSection(in);
          break;
        case STRING_TABLE:
          loadStringTableSection(in);
          break;
        case INODE: {
          currentStep = new Step(StepType.INODES);
          prog.beginStep(Phase.LOADING_FSIMAGE, currentStep);
          stageSubSections = getSubSectionsOfName(
              subSections, SectionName.INODE_SUB);
          if (loadInParallel && (stageSubSections.size() > 0)) {
            inodeLoader.loadINodeSectionInParallel(executorService,
                stageSubSections, summary.getCodec(), prog, currentStep);

View on GitHub (pinned to 2add963021)

Solutions

1. Read the image with the same or newer Hadoop release that wrote it (e.g. run 'hdfs oiv' from the writer's installation) and convert or re-save it
2. Verify version compatibility on a test node of the writer's version before loading on the cluster
3. If the image is corrupt, restore fsimage from another name.dir or the last good checkpoint and replay edits from there
4. Never modify fsimage bytes by hand; use OfflineImageViewer/OfflineEditsViewer for inspection and conversion

Example fix

# before: older binaries fail on an image written by a newer release
hdfs oiv -i /dfs/name/current/fsimage_0000000000000050000 -p XML -o out.xml
# after: use the release that wrote the image (or newer)
/opt/hadoop-3.3.6/bin/hdfs oiv -i /dfs/name/current/fsimage_0000000000000050000 -p XML -o out.xml

FileSummary s = FSImageUtil.loadSummary(new RandomAccessFile(img, "r"));
if (!NameNodeLayoutVersion.supports(
        NameNodeLayoutVersion.Feature.PROTOBUF_FORMAT,
        s.getLayoutVersion())) {
  throw new IOException("fsimage not readable by this build; "
      + "layout version " + s.getLayoutVersion());
}

try { new FSImageFormatProtobuf.Loader(conf, fsn).load(file); } catch (IOException e) { /* 'Unrecognized section' => this build cannot parse the image; do NOT retry the same file; switch to another checkpoint copy or a compatible Hadoop version */ }

When it happens

Trigger: Loading an fsimage (NameNode startup on a checkpoint, or 'hdfs oiv' / OfflineImageViewer) whose FileSummary contains a section name unknown to the running build; typical when a newer release introduced a new section type and the file is read by older binaries, or after a downgrade; also from a truncated/hand-edited fsimage.

Common situations: Downgrading a cluster after a rolling upgrade; copying fsimage between clusters running different Hadoop versions; an interrupted fsimage copy or bit rot; running an old 'hdfs oiv' against a new-format image.

Related errors

• Unsupported file version {}
• 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/21c66616d4b9dafd. Report an issue: GitHub.