{"record":{"id":"96cb948256967e2d","repo":"apache/hadoop","slug":"error-96cb94","errorCode":null,"errorMessage":"{}","messagePattern":"\\{\\}","errorType":"exception","errorClass":"PathIsNotDirectoryException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/INodeDirectory.java","lineNumber":65,"sourceCode":"import 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,\n      long mtime) {\n    super(id, name, permissions, mtime, 0L);\n  }\n  ","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/INodeDirectory.java#L47-L83","documentation":"INodeDirectory.valueOf throws PathIsNotDirectoryException when the path resolves to an INode that exists but is not a directory (a regular file or symlink). HDFS uses this distinct exception type so callers can separate 'missing path' from 'wrong kind of path' — it maps to a client-side 'Not a directory' error.","triggerScenarios":"Passing a file path where the code requires a directory (e.g. rename destination parent is a file); internal listing/quota operations on a path occupied by a file; a symlink where the caller did not resolve the target.","commonSituations":"Path-building bugs where an earlier step created the component as a file; applications that store data at a path later reused as a directory; tools that do not follow symlinks.","solutions":["Check FileStatus/isDirectory() first and use the correct path","If the location must be a directory, move or delete the conflicting file (verify ownership of the data first)","Catch PathIsNotDirectoryException explicitly and surface a precise error to the client instead of a generic failure"],"exampleFix":"// before\nINodeDirectory dir = INodeDirectory.valueOf(node, path); // path is a file -> throws\n\n// after\nif (!node.isDirectory()) {\n  throw new PathIsNotDirectoryException(DFSUtil.path2String(path));\n}\nINodeDirectory dir = INodeDirectory.valueOf(node, path);","handlingStrategy":"type-guard","validationCode":"// Client-side: stat before using a path as a directory\nFileStatus st = fs.getFileStatus(path);\nif (!st.isDirectory()) {\n  throw new IllegalArgumentException(\"Expected directory, got file/symlink: \" + path);\n}","typeGuard":"boolean isUsableDirectory(FileSystem fs, Path p) throws IOException {\n  FileStatus st = fs.getFileStatus(p);\n  return st.isDirectory();   // false for files and symlinks\n}","tryCatchPattern":"catch (PathIsNotDirectoryException e) {\n  // wrong-kind path: fix the path or fail with a precise message; not retryable\n  throw new IllegalArgumentException(e.getPath() + \" must be a directory\", e);\n}","preventionTips":["Validate path kind once at configuration load for user-supplied directory settings","Prefer explicit create(mkdirs) over assuming layout","Distinguish PathIsNotDirectoryException from FileNotFoundException in handlers — different remedies"],"tags":["hdfs","namenode","path-type","namespace"],"backgroundTag":"path-type-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}