apache/hadoop · error · IOException

Unrecognized section {s.getName()}

Error message

Unrecognized section {s.getName()}

What it means

After reading the fsimage FileSummary, FSImageLoader iterates its sections and maps each section name through FSImageFormatProtobuf.SectionName.fromString(); an unknown name returns null and this IOException is thrown. It means the image contains a section type this oiv build does not know — classically an fsimage written by a newer Hadoop being read by an older tool.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/FSImageLoader.java:164

              }
            }
          });

      for (FsImageProto.FileSummary.Section s : sections) {
        fin.getChannel().position(s.getOffset());
        InputStream is = FSImageUtil.wrapInputStreamForCompression(conf,
            summary.getCodec(), new BufferedInputStream(new LimitInputStream(
            fin, s.getLength())));

        if (LOG.isDebugEnabled()) {
          LOG.debug("Loading section " + s.getName() + " length: " + s.getLength
              ());
        }

        FSImageFormatProtobuf.SectionName sectionName
            = FSImageFormatProtobuf.SectionName.fromString(s.getName());
        if (sectionName == null) {
          throw new IOException("Unrecognized section " + s.getName());
        }
        switch (sectionName) {
          case STRING_TABLE:
            stringTable = loadStringTable(is);
            break;
          case INODE:
            inodes = loadINodeSection(is);
            break;
          case INODE_REFERENCE:
            refIdList = loadINodeReferenceSection(is);
            break;
          case INODE_DIR:
            dirmap = loadINodeDirectorySection(is, refIdList);
            break;
          default:
            break;
        }
      }

View on GitHub (pinned to 2add963021)

Solutions

1. Run oiv from a Hadoop distribution at least as new as the NameNode that wrote the fsimage.
2. Compare hadoop version on both sides; the section names your build understands are exactly the enum constants in FSImageFormatProtobuf.SectionName.
3. Since oiv needs no cluster access, just upgrade the tool box's Hadoop to the cluster version or newer.

Example fix

# before (workstation has old hadoop)
/opt/hadoop-2.7/bin/hdfs oiv -i fsimage_new -p XML -o out.xml
# -> Unrecognized section ...

# after (use the cluster's version or newer)
/opt/hadoop-3.3/bin/hdfs oiv -i fsimage_new -p XML -o out.xml

// before loading, confirm the tool knows every section in the image summary
for (FileSummary.Section s : summary.getSectionsList()) {
  if (FSImageFormatProtobuf.SectionName.fromString(s.getName()) == null) {
    throw new IOException("Image needs a newer oiv; unknown section " + s.getName());
  }
}

try {
  FSImageLoader.load(inputFile);
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unrecognized section")) {
    // version skew: rerun with an oiv at least as new as the cluster that wrote the image
    throw new IOException("oiv too old for this fsimage: " + e.getMessage(), e);
  }
  throw e;
}

When it happens

Trigger: Running an older hadoop distribution's oiv against an fsimage from a newer release that introduced new section names (e.g. erasure-coding-era sections added after this build); images written by patched NameNodes with custom sections.

Common situations: Version skew between the analysis workstation's Hadoop and the cluster; images copied from a newer cluster analyzed with stale tooling; images captured mid rolling-upgrade.

Related errors

• Unrecognized FSImage
• Unrecognized FSImage
• Unrecognized section {}
• Unsupported file version {}
• Too many distribution intervals {numIntervals}

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