apache/hadoop · critical · java.io.IOException

Failed to load FSImage file, see error(s) above for more inf

Error message

Failed to load FSImage file, see error(s) above for more info.

What it means

loadFSImageAll() exhausted every candidate fsimage without success — each failed attempt logged an ERROR (corruption, md5 mismatch, unreadable file, unsupported layout) and cleared the in-memory target — so the loop ends with no usable image and startup aborts with this summary. The actionable diagnostics are the per-file ERROR lines just above this exception; edit streams are closed before throwing.

Source

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

    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,
          startOpt, recovery);
      prog.endPhase(Phase.LOADING_EDITS);
      needToSave |= needsResaveBasedOnStaleCheckpoint(imageFile.getFile(),
          txnsAdvanced);
    } else {
      // Trigger the rollback for rolling upgrade. Here lastAppliedTxId equals
      // to the last txid in rollback fsimage.
      rollingRollback(lastAppliedTxId + 1, imageFiles.get(0).getCheckpointTxId());
      needToSave = false;
    }
    editLog.setNextTxId(lastAppliedTxId + 1);

View on GitHub (pinned to 2add963021)

Solutions

1. Read the ERROR lines above this exception — they identify each failed file and the reason.
2. Restore a good fsimage (plus its .md5 and edits) from the Standby NameNode, Secondary checkpoint, or backups into <name.dir>/current/.
3. If the md5 mismatch is from a known intentional modification, regenerate the sidecar deliberately: md5sum fsimage_N > fsimage_N.md5.
4. Only with no recoverable copy: 'hdfs namenode -format' — total metadata loss that orphans all block data.

Example fix

# before
hdfs --daemon start namenode
# IOException: Failed to load FSImage file, see error(s) above for more info.

# after: restore from Standby/checkpoint copy
scp standby-nn:/dfs/nn/current/fsimage_* /dfs/nn/current/
scp standby-nn:/dfs/nn/current/fsimage_*.md5 /dfs/nn/current/
hdfs --daemon start namenode

File img = newestFsImage; // newest fsimage_* in current/
MD5Hash stored = MD5FileUtils.readStoredMd5ForFile(img);
if (!stored.equals(MD5FileUtils.computeMd5ForFile(img))) {
  // quarantine this image before the NameNode ever tries it
}

try {
  fsImage.loadFSImage(startOpt);
} catch (IOException e) {
  // fatal: collect the per-file ERROR causes from the log, then restore a known-good image from Standby/backup
}

When it happens

Trigger: All fsimage_* files corrupt (disk fault, truncated copy, md5 mismatch); images written by a newer Hadoop layout being read by older binaries; current/ containing no fsimage at all.

Common situations: Disk corruption on the metadata volume; partial rsync/scp of metadata between hosts; manual image edits breaking the md5; version downgrade attempts.

Related errors

• The length of the feature flag section was negative at {} by
• Same delegation token being added twice; invalid entry in fs
• Error replaying edit log at offset {}. Expected transaction
• Failed to load image from {imageFile}
• No valid image files found

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