apache/hadoop · critical · java.io.IOException

Failed to load image from {imageFile}

Error message

Failed to load image from {imageFile}

What it means

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.

Source

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

    for (EditLogInputStream elis : editStreams) {
      elis.setMaxOpSize(maxOpSize);
    }
 
    for (EditLogInputStream l : editStreams) {
      LOG.debug("Planning to load edit log stream: {}.", l);
    }
    if (!editStreams.iterator().hasNext()) {
      LOG.info("No edit log streams selected.");
    }
    
    FSImageFile imageFile = null;
    for (int i = 0; i < imageFiles.size(); i++) {
      try {
        imageFile = imageFiles.get(i);
        loadFSImageFile(target, recovery, imageFile, startOpt);
        break;
      } catch (IllegalReservedPathException ie) {
        throw new IOException("Failed to load image from " + imageFile,
            ie);
      } catch (Exception e) {
        LOG.error("Failed to load image from " + imageFile, e);
        target.clear();
        imageFile = null;
      }
    }
    // Failed to load any images, error out
    if (imageFile == null) {
      FSEditLog.closeAllStreams(editStreams);
      throw new IOException("Failed to load FSImage file, see error(s) " +
          "above for more info.");
    }
    prog.endPhase(Phase.LOADING_FSIMAGE);
    
    if (!rollingRollback) {
      prog.beginPhase(Phase.LOADING_EDITS);
      long txnsAdvanced = loadEdits(editStreams, target, Long.MAX_VALUE,

View on GitHub (pinned to 2add963021)

Solutions

1. Read the cause chain — IllegalReservedPathException names the offending path.
2. 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.
3. If no backup exists, use NameNode recovery tooling or rebuild the namespace from audit logs.
4. Fix whatever produced the reserved paths before new images are written.

Example fix

# before
hdfs --daemon start namenode
# IOException: Failed to load image from fsimage_0100

# after: fall back to the previous image + edits replay
mkdir -p /backup && mv /dfs/nn/current/fsimage_0100* /backup/
hdfs --daemon start namenode   # loads fsimage_0099, then replays edits

try {
  fsImage.loadFSImage(startOpt);
} catch (IOException e) {
  if (e.getCause() instanceof IllegalReservedPathException) {
    // do not blindly retry other images: quarantine this one and restore a known-good copy
  }
}

When it happens

Trigger: 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.

Common situations: Rare on healthy clusters; seen after third-party metadata manipulation, filesystem migrations, or bit-level corruption of the image file.

Related errors

• Failed to load FSImage file, see error(s) above for more inf
• No valid image files found
• Unknown nameservice: {}
• Configuration has multiple addresses that match local node's
• Configuration dfs.namenode.rpc-address must be suffixed with

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