{"record":{"id":"25bc2b75346f6f7d","repo":"apache/hadoop","slug":"path-is-not-a-file","errorCode":null,"errorMessage":"Path is not a file: {}","messagePattern":"Path is not a file: (.+?)","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/INodeFile.java","lineNumber":91,"sourceCode":"\n  /** The same as valueOf(inode, path, false). */\n  public static INodeFile valueOf(INode inode, String path\n      ) throws FileNotFoundException {\n    return valueOf(inode, path, false);\n  }\n\n  /** Cast INode to INodeFile. */\n  public static INodeFile valueOf(INode inode, String path, boolean acceptNull)\n      throws FileNotFoundException {\n    if (inode == null) {\n      if (acceptNull) {\n        return null;\n      } else {\n        throw new FileNotFoundException(\"File does not exist: \" + path);\n      }\n    }\n    if (!inode.isFile()) {\n      throw new FileNotFoundException(\"Path is not a file: \" + path);\n    }\n    return inode.asFile();\n  }\n\n  /** \n   * Bit format:\n   * [4-bit storagePolicyID][12-bit BLOCK_LAYOUT_AND_REDUNDANCY]\n   * [48-bit preferredBlockSize]\n   *\n   * BLOCK_LAYOUT_AND_REDUNDANCY contains 12 bits and describes the layout and\n   * redundancy of a block. We use the highest 1 bit to determine whether the\n   * block is replica or erasure coded. For replica blocks, the tail 11 bits\n   * stores the replication factor. For erasure coded blocks, the tail 11 bits\n   * stores the EC policy ID, and in the future, we may further divide these\n   * 11 bits to store both the EC policy ID and replication factor for erasure\n   * coded blocks. The layout of this section is demonstrated as below.\n   *\n   * Another possible future extension is for future block types, in which case","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/INodeFile.java#L73-L109","documentation":"INodeFile.valueOf throws FileNotFoundException(\"Path is not a file: <path>\") when the path exists but resolves to something other than a regular file — typically a directory, or a symlink. Note that HDFS deliberately reuses FileNotFoundException for this wrong-type case, so the message (not the class) distinguishes it from a truly missing file.","triggerScenarios":"Opening, appending to, or validating a path that is actually a directory; a symlink passed to a file-only API without following the link; path construction that dropped the final file component.","commonSituations":"Directories used as placeholders where code later expects a file; datasets addressed at directory roots while the client opens them as files; symlink-aware tools hitting raw links.","solutions":["Check inode.isFile() / FileStatus.isFile() first and branch or fix the path","Correct the path construction (missing filename component, wrong separator)","When catching, inspect the message ('Path is not a file') to distinguish wrong-type from missing"],"exampleFix":"// before\nINodeFile f = INodeFile.valueOf(node, path); // path is a directory -> throws\n\n// after\nif (!node.isFile()) {\n  throw new FileNotFoundException(\"Path is not a file: \" + path);\n}\nINodeFile f = INodeFile.valueOf(node, path);","handlingStrategy":"type-guard","validationCode":"// Client-side: confirm regular file before file-only APIs\nFileStatus st = fs.getFileStatus(path);\nif (!st.isFile()) {\n  throw new IllegalArgumentException(\"Expected a file: \" + path\n      + \" (isDirectory=\" + st.isDirectory()\n      + \", isSymlink=\" + st.isSymlink() + \")\");\n}","typeGuard":"boolean isRegularFile(FileSystem fs, Path p) throws IOException {\n  FileStatus st = fs.getFileStatus(p);\n  return st.isFile() && !st.isSymlink();\n}","tryCatchPattern":"catch (FileNotFoundException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Path is not a file\")) {\n    throw new IllegalArgumentException(\"Path is a directory or symlink: \" + path, e);\n  }\n  throw e; // genuinely missing file\n}","preventionTips":["Validate user-supplied file paths with getFileStatus().isFile() at input boundaries","Parse the exception message to separate wrong-type from missing — same exception class covers both","Resolve symlinks explicitly when the operation targets the destination file"],"tags":["hdfs","namenode","path-type","file-not-found","namespace"],"backgroundTag":"path-type-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}