{"record":{"id":"826ad258c3a2da43","repo":"apache/hadoop","slug":"no-valid-image-files-found","errorCode":null,"errorMessage":"No valid image files found","messagePattern":"No valid image files found","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImageTransactionalStorageInspector.java","lineNumber":159,"sourceCode":"   */\n  @Override\n  List<FSImageFile> getLatestImages() throws IOException {\n    LinkedList<FSImageFile> ret = new LinkedList<FSImageFile>();\n    for (FSImageFile img : foundImages) {\n      if (ret.isEmpty()) {\n        ret.add(img);\n      } else {\n        FSImageFile cur = ret.getFirst();\n        if (cur.txId == img.txId) {\n          ret.add(img);\n        } else if (cur.txId < img.txId) {\n          ret.clear();\n          ret.add(img);\n        }\n      }\n    }\n    if (ret.isEmpty()) {\n      throw new FileNotFoundException(\"No valid image files found\");\n    }\n    return ret;\n  }\n  \n  public List<FSImageFile> getFoundImages() {\n    return ImmutableList.copyOf(foundImages);\n  }\n  \n  @Override\n  public boolean needToSave() {\n    return needToSave;\n  }\n\n  @Override\n  long getMaxSeenTxId() {\n    return maxSeenTxId;\n  }\n}","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImageTransactionalStorageInspector.java#L141-L177","documentation":"The transactional storage inspector (Hadoop 2.x+ checkpoint layout, fsimage_<txid>) scans all dfs.namenode.name.dir directories for image files. If not one fsimage is found, getLatestImages() throws FileNotFoundException('No valid image files found') and the NameNode cannot boot — almost always unformatted or misconfigured name directories rather than corruption.","triggerScenarios":"getLatestImages() after inspectStorage() located zero fsimage_<txid> files: fresh install never formatted, dfs.namenode.name.dir pointing at empty or wrong paths, images deleted, or a mount not attached.","commonSituations":"First startup without 'hdfs namenode -format'; typo'd or stale name.dir after host migration; disk unmounted; images removed by cleanup scripts.","solutions":["Confirm what is on disk: ls <name.dir>/current for every configured directory","Fix dfs.namenode.name.dir to the real storage paths and restart","For a brand-new/dev cluster run 'hdfs namenode -format' (destroys the namespace — dev only)","For an existing cluster restore fsimage_<txid> + fsimage.md5 + seen_txid from backup, or import a checkpoint"],"exampleFix":"# before: empty storage dir\nls /dfs/name/current/   # nothing (or no current/ at all)\n# after: either restore a checkpoint ...\ncp /backup/fsimage_0000000000000085000* /backup/seen_txid /dfs/name/current/\n# ... or, for a throwaway dev cluster\nhdfs namenode -format","handlingStrategy":"validation","validationCode":"for (URI u : FSNamesystem.getNamespaceDirs(conf)) {\n  File cur = new File(u.getPath(), Storage.STORAGE_DIR_CURRENT);\n  File[] imgs = cur.listFiles((d, n) -> n.startsWith(\"fsimage_\"));\n  if (imgs == null || imgs.length == 0) {\n    LOG.error(\"no fsimage_<txid> in \" + cur + \" - NameNode will fail to start\");\n  }\n}","typeGuard":null,"tryCatchPattern":"catch FileNotFoundException from FSImage loading — distinguish 'no valid image files found' (unformatted/wrong dirs; fix config or format) from per-file IO errors before retrying.","preventionTips":["Run 'hdfs namenode -format' exactly once per dev cluster and snapshot the dir","Automate a pre-start check that each name.dir/current holds at least one fsimage_<txid>","Alert on near-empty current/ directories so accidental deletion is caught before restart"],"tags":["hadoop","hdfs","namenode","fsimage","storage-dir","startup"],"backgroundTag":"missing-checkpoint-file","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}