apache/hadoop · error · IOException

Unrecognized section {}

Error message

Unrecognized section {}

What it means

The fsimage trailer (FileSummary protobuf) lists every section the image contains, and SectionName.fromString() maps each name to a known type. A null mapping means the image contains a section type this oiv build predates; the text writer aborts instead of silently omitting that section's data.

Source

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

              if (n1 == null) {
                return n2 == null ? 0 : -1;
              } else if (n2 == null) {
                return -1;
              } else {
                return n1.ordinal() - n2.ordinal();
              }
            }
          });

      ImmutableList<Long> refIdList = null;
      for (FileSummary.Section section : sections) {
        fin.getChannel().position(section.getOffset());
        is = FSImageUtil.wrapInputStreamForCompression(conf,
            summary.getCodec(), new BufferedInputStream(new LimitInputStream(
                fin, section.getLength())));
        SectionName sectionName = SectionName.fromString(section.getName());
        if (sectionName == null) {
          throw new IOException("Unrecognized section " + section.getName());
        }
        switch (sectionName) {
        case STRING_TABLE:
          LOG.info("Loading string table");
          stringTable = FSImageLoader.loadStringTable(is);
          break;
        case INODE_REFERENCE:
          // Load INodeReference so that all INodes can be processed.
          // Snapshots are not handled and will just be ignored for now.
          LOG.info("Loading inode references");
          refIdList = FSImageLoader.loadINodeReferenceSection(is);
          break;
        default:
          break;
        }
      }

      loadDirectories(fin, sections, summary, conf);

View on GitHub (pinned to 2add963021)

Solutions

1. Run oiv from a distribution at least as new as the NameNode that wrote the image (compare `hdfs version` with the image's layoutVersion)
2. Copy the fsimage to a host with the correct-version Hadoop install and run oiv there
3. There is no skip flag for unknown sections — upgrading the tooling is the only supported path

Example fix

# before: old tool, new image
/opt/hadoop-2.8/bin/hdfs oiv -p delimited -i fsimage_new -o out.csv
# IOException: Unrecognized section ...

# after: matching (or newer) tool
/opt/hadoop-3.3/bin/hdfs oiv -p delimited -i fsimage_new -o out.csv

try {
  // PBImageTextWriter visit
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unrecognized section")) {
    // oiv build is older than the image: rerun with a matching-version tool
    LOG.error("oiv too old for this fsimage: {}", e.getMessage());
  }
  throw e;
}

When it happens

Trigger: Reading a fsimage written by a newer Hadoop release that introduced a new section type (its name appears in the exception) with an older `hdfs oiv` binary; the section name in the message identifies exactly which section the tool does not know.

Common situations: oiv taken from an old tarball or cluster install and pointed at a newer cluster's fsimage; mixed-version tooling right after a cluster upgrade.

Related errors

• Cannot process fslayout version {imageVersion}
• Unrecognized section {}
• Unrecognized section {}
• Unsupported file version {}
• String table bits ${bits} > ${maskBits}

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