{"record":{"id":"8f8543b0ac6be2f1","repo":"apache/hadoop","slug":"pathhandle-only-available-for-files-8f8543","errorCode":null,"errorMessage":"PathHandle only available for files","messagePattern":"PathHandle only available for files","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DistributedFileSystem.java","lineNumber":496,"sourceCode":"\n  /**\n   * Create a handle to an HDFS file.\n   * @param st HdfsFileStatus instance from NameNode\n   * @param opts Standard handle arguments\n   * @throws IllegalArgumentException If the FileStatus instance refers to a\n   * directory, symlink, or another namesystem.\n   * @throws UnsupportedOperationException If opts are not specified or both\n   * data and location are not allowed to change.\n   * @return A handle to the file.\n   */\n  @Override\n  protected HdfsPathHandle createPathHandle(FileStatus st, HandleOpt... opts) {\n    if (!(st instanceof HdfsFileStatus)) {\n      throw new IllegalArgumentException(\"Invalid FileStatus \"\n          + st.getClass().getSimpleName());\n    }\n    if (st.isDirectory() || st.isSymlink()) {\n      throw new IllegalArgumentException(\"PathHandle only available for files\");\n    }\n    if (!getUri().getAuthority().equals(st.getPath().toUri().getAuthority())) {\n      throw new IllegalArgumentException(\"Wrong FileSystem: \" + st.getPath());\n    }\n    HandleOpt.Data data = HandleOpt.getOpt(HandleOpt.Data.class, opts)\n        .orElse(HandleOpt.changed(false));\n    HandleOpt.Location loc = HandleOpt.getOpt(HandleOpt.Location.class, opts)\n        .orElse(HandleOpt.moved(false));\n\n    HdfsFileStatus hst = (HdfsFileStatus) st;\n    final Path p;\n    final Optional<Long> inodeId;\n    if (loc.allowChange()) {\n      p = DFSUtilClient.makePathFromFileId(hst.getFileId());\n      inodeId = Optional.empty();\n    } else {\n      p = hst.getPath();\n      inodeId = Optional.of(hst.getFileId());","sourceCodeStart":478,"sourceCodeEnd":514,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DistributedFileSystem.java#L478-L514","documentation":"Error \"PathHandle only available for files\" thrown in apache/hadoop.","triggerScenarios":"open(PathHandle) is called with a FileStatus that refers to a directory; path handles are only issued for files.","commonSituations":"See trigger scenarios.","solutions":["Request a PathHandle only for regular files, not directories or symlinks.","Check FileStatus.isFile() before calling open(PathHandle) or related APIs."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}