{"record":{"id":"e2ee2b8827d1e806","repo":"apache/hadoop","slug":"directory-does-not-exist","errorCode":null,"errorMessage":"Directory does not exist: {}","messagePattern":"Directory does not exist: (.+?)","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/INodeDirectory.java","lineNumber":61,"sourceCode":"import org.apache.hadoop.hdfs.util.ReadOnlyList;\n\nimport org.apache.hadoop.classification.VisibleForTesting;\nimport org.apache.hadoop.util.Preconditions;\nimport org.apache.hadoop.security.AccessControlException;\n\nimport static org.apache.hadoop.hdfs.protocol.HdfsConstants.BLOCK_STORAGE_POLICY_ID_UNSPECIFIED;\n\n/**\n * Directory INode class.\n */\npublic class INodeDirectory extends INodeWithAdditionalFields\n    implements INodeDirectoryAttributes {\n\n  /** Cast INode to INodeDirectory. */\n  public static INodeDirectory valueOf(INode inode, Object path\n      ) throws FileNotFoundException, PathIsNotDirectoryException {\n    if (inode == null) {\n      throw new FileNotFoundException(\"Directory does not exist: \"\n          + DFSUtil.path2String(path));\n    }\n    if (!inode.isDirectory()) {\n      throw new PathIsNotDirectoryException(DFSUtil.path2String(path));\n    }\n    return inode.asDirectory(); \n  }\n\n  // Profiling shows that most of the file lists are between 1 and 4 elements.\n  // Thus allocate the corresponding ArrayLists with a small initial capacity.\n  public static final int DEFAULT_FILES_PER_DIRECTORY = 2;\n\n  static final byte[] ROOT_NAME = DFSUtil.string2Bytes(\"\");\n\n  private List<INode> children = null;\n  \n  /** constructor */\n  public INodeDirectory(long id, byte[] name, PermissionStatus permissions,","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/INodeDirectory.java#L43-L79","documentation":"INodeDirectory.valueOf(INode, path) throws FileNotFoundException(\"Directory does not exist: <path>\") when the resolved INode is null, meaning the path is absent from the namespace. This is the NameNode-internal cast helper used wherever a path component must be a directory (rename parents, quota updates, listings), so the exception surfaces through the RPC layer as a client-visible 'no such file or directory'.","triggerScenarios":"An internal FSDirectory operation resolves a parent/target directory that was concurrently deleted; calling valueOf on a path that was never created; snapshot/rollback leaving code with a stale path string.","commonSituations":"Check-then-act races where a client verifies existence and another client deletes the directory before the operation lands; application code assuming a parent directory exists without mkdirs; replaying captured operations against a changed namespace.","solutions":["Create the directory first (mkdirs) before operations that require it as a parent","When writing NN-side code, re-resolve via FSDirectory.getINode and handle null explicitly instead of calling valueOf blindly","For concurrency races, catch FileNotFoundException and either retry the whole operation or report the deletion to the caller"],"exampleFix":"// before\nINodeDirectory dir = INodeDirectory.valueOf(fsDir.getINode(path, DirOp.READ), path);\n\n// after\nINode node = fsDir.getINode(path, DirOp.READ);\nif (node == null) {\n  throw new FileNotFoundException(\"Directory does not exist: \" + path);\n}\nINodeDirectory dir = INodeDirectory.valueOf(node, path);","handlingStrategy":"validation","validationCode":"// NN-side: resolve first, distinguish missing from wrong-type\nINode node = fsDir.getINode(path, DirOp.READ);\nif (node == null) {\n  // missing: create it or report precisely\n  throw new FileNotFoundException(\"Directory does not exist: \" + DFSUtil.path2String(path));\n}\nINodeDirectory dir = INodeDirectory.valueOf(node, path);","typeGuard":"static boolean isExistingDirectory(FSDirectory fsDir, String path) {\n  final INode n;\n  try {\n    fsDir.readLock();\n    n = fsDir.getINode(path, DirOp.READ);\n  } finally {\n    fsDir.readUnlock();\n  }\n  return n != null && n.isDirectory();\n}","tryCatchPattern":"catch (FileNotFoundException e) {\n  // path vanished (possibly deleted concurrently): decide recreate vs report\n  if (isRetryableRace(e)) { retryOperation(); } else { reportMissingPath(e); }\n}","preventionTips":["mkdirs() parents before rename/create flows that assume they exist","Never cache directory paths across long-lived operations; re-resolve per request","Make clients idempotent so delete races surface as clean retries, not failures"],"tags":["hdfs","namenode","namespace","file-not-found","race-condition"],"backgroundTag":"path-not-found","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}