{"record":{"id":"21c66616d4b9dafd","repo":"apache/hadoop","slug":"unrecognized-section","errorCode":null,"errorMessage":"Unrecognized section {}","messagePattern":"Unrecognized section (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImageFormatProtobuf.java","lineNumber":422,"sourceCode":"      ExecutorService executorService = null;\n      ArrayList<FileSummary.Section> subSections =\n          getAndRemoveSubSections(sections);\n      if (loadInParallel) {\n        executorService = getParallelExecutorService();\n      }\n\n      for (FileSummary.Section s : sections) {\n        channel.position(s.getOffset());\n        InputStream in = new BufferedInputStream(new LimitInputStream(fin,\n            s.getLength()));\n\n        in = FSImageUtil.wrapInputStreamForCompression(conf,\n            summary.getCodec(), in);\n\n        String n = s.getName();\n        SectionName sectionName = SectionName.fromString(n);\n        if (sectionName == null) {\n          throw new IOException(\"Unrecognized section \" + n);\n        }\n\n        ArrayList<FileSummary.Section> stageSubSections;\n        switch (sectionName) {\n        case NS_INFO:\n          loadNameSystemSection(in);\n          break;\n        case STRING_TABLE:\n          loadStringTableSection(in);\n          break;\n        case INODE: {\n          currentStep = new Step(StepType.INODES);\n          prog.beginStep(Phase.LOADING_FSIMAGE, currentStep);\n          stageSubSections = getSubSectionsOfName(\n              subSections, SectionName.INODE_SUB);\n          if (loadInParallel && (stageSubSections.size() > 0)) {\n            inodeLoader.loadINodeSectionInParallel(executorService,\n                stageSubSections, summary.getCodec(), prog, currentStep);","sourceCodeStart":404,"sourceCodeEnd":440,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImageFormatProtobuf.java#L404-L440","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Verify version compatibility on a test node of the writer's version before loading on the cluster","If the image is corrupt, restore fsimage from another name.dir or the last good checkpoint and replay edits from there","Never modify fsimage bytes by hand; use OfflineImageViewer/OfflineEditsViewer for inspection and conversion"],"exampleFix":"# before: older binaries fail on an image written by a newer release\nhdfs oiv -i /dfs/name/current/fsimage_0000000000000050000 -p XML -o out.xml\n# after: use the release that wrote the image (or newer)\n/opt/hadoop-3.3.6/bin/hdfs oiv -i /dfs/name/current/fsimage_0000000000000050000 -p XML -o out.xml","handlingStrategy":"validation","validationCode":"FileSummary s = FSImageUtil.loadSummary(new RandomAccessFile(img, \"r\"));\nif (!NameNodeLayoutVersion.supports(\n        NameNodeLayoutVersion.Feature.PROTOBUF_FORMAT,\n        s.getLayoutVersion())) {\n  throw new IOException(\"fsimage not readable by this build; \"\n      + \"layout version \" + s.getLayoutVersion());\n}","typeGuard":null,"tryCatchPattern":"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 */ }","preventionTips":["Run one Hadoop version across everything that reads or writes fsimage (NN, SNN/standby, oiv tooling)","Finish rolling upgrades before taking new checkpoints","Verify fsimage.md5 after any copy of an image"],"tags":["hadoop","hdfs","namenode","fsimage","protobuf","version-mismatch"],"backgroundTag":"file-format-version-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}