{"record":{"id":"0a5d68da71333d73","repo":"apache/hadoop","slug":"failed-to-load-image-from-imagefile","errorCode":null,"errorMessage":"Failed to load image from {imageFile}","messagePattern":"Failed to load image from (.+?)","errorType":"exception","errorClass":"java.io.IOException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImage.java","lineNumber":745,"sourceCode":"    for (EditLogInputStream elis : editStreams) {\n      elis.setMaxOpSize(maxOpSize);\n    }\n \n    for (EditLogInputStream l : editStreams) {\n      LOG.debug(\"Planning to load edit log stream: {}.\", l);\n    }\n    if (!editStreams.iterator().hasNext()) {\n      LOG.info(\"No edit log streams selected.\");\n    }\n    \n    FSImageFile imageFile = null;\n    for (int i = 0; i < imageFiles.size(); i++) {\n      try {\n        imageFile = imageFiles.get(i);\n        loadFSImageFile(target, recovery, imageFile, startOpt);\n        break;\n      } catch (IllegalReservedPathException ie) {\n        throw new IOException(\"Failed to load image from \" + imageFile,\n            ie);\n      } catch (Exception e) {\n        LOG.error(\"Failed to load image from \" + imageFile, e);\n        target.clear();\n        imageFile = null;\n      }\n    }\n    // Failed to load any images, error out\n    if (imageFile == null) {\n      FSEditLog.closeAllStreams(editStreams);\n      throw new IOException(\"Failed to load FSImage file, see error(s) \" +\n          \"above for more info.\");\n    }\n    prog.endPhase(Phase.LOADING_FSIMAGE);\n    \n    if (!rollingRollback) {\n      prog.beginPhase(Phase.LOADING_EDITS);\n      long txnsAdvanced = loadEdits(editStreams, target, Long.MAX_VALUE,","sourceCodeStart":727,"sourceCodeEnd":763,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImage.java#L727-L763","documentation":"In loadFSImageAll(), loading a specific fsimage candidate raised IllegalReservedPathException — the image contains a path using reserved/illegal constructs (such as /.reserved sequences). Reserved-path violations are treated as systemic (an older image would just hide metadata damage), so instead of falling back the loader wraps the exception in an IOException naming the file and rethrows immediately.","triggerScenarios":"Loading a fsimage written by an incompatible or buggy release that allowed reserved paths; hand-modified or corrupted images; namespaces polluted by external metadata tools or migrations that introduced reserved names.","commonSituations":"Rare on healthy clusters; seen after third-party metadata manipulation, filesystem migrations, or bit-level corruption of the image file.","solutions":["Read the cause chain — IllegalReservedPathException names the offending path.","Restore the previous good fsimage from the Standby/Secondary/backup; or move the bad fsimage_N and its .md5 aside so the loader picks the prior image and replays edits from there.","If no backup exists, use NameNode recovery tooling or rebuild the namespace from audit logs.","Fix whatever produced the reserved paths before new images are written."],"exampleFix":"# before\nhdfs --daemon start namenode\n# IOException: Failed to load image from fsimage_0100\n\n# after: fall back to the previous image + edits replay\nmkdir -p /backup && mv /dfs/nn/current/fsimage_0100* /backup/\nhdfs --daemon start namenode   # loads fsimage_0099, then replays edits","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  fsImage.loadFSImage(startOpt);\n} catch (IOException e) {\n  if (e.getCause() instanceof IllegalReservedPathException) {\n    // do not blindly retry other images: quarantine this one and restore a known-good copy\n  }\n}","preventionTips":["Never let external tools rewrite fsimage files.","Keep a Standby NameNode / backups so a bad image is never the only copy.","Test image loads after any metadata surgery."],"tags":["hdfs","namenode","fsimage","reserved-path","startup"],"backgroundTag":"fsimage-load-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}