{"record":{"id":"be72809e6d116a5a","repo":"apache/hadoop","slug":"path-is-a-file-path","errorCode":null,"errorMessage":"Path is a file: {path}","messagePattern":"Path is a file: (.+?)","errorType":"exception","errorClass":"FileAlreadyExistsException","httpStatus":null,"severity":"error","filePath":"hadoop-tools/hadoop-aliyun/src/main/java/org/apache/hadoop/fs/aliyun/oss/AliyunOSSFileSystem.java","lineNumber":572,"sourceCode":"    if (StringUtils.isNotEmpty(key)) {\n      if (!key.endsWith(\"/\")) {\n        dirName += \"/\";\n      }\n      store.storeEmptyFile(dirName);\n    }\n    return true;\n  }\n\n  @Override\n  public boolean mkdirs(Path path, FsPermission permission)\n      throws IOException {\n    try {\n      FileStatus fileStatus = getFileStatus(path);\n\n      if (fileStatus.isDirectory()) {\n        return true;\n      } else {\n        throw new FileAlreadyExistsException(\"Path is a file: \" + path);\n      }\n    } catch (FileNotFoundException e) {\n      validatePath(path);\n      String key = pathToKey(path);\n      return mkdir(key);\n    }\n  }\n\n  /**\n   * Check whether the path is a valid path.\n   *\n   * @param path the path to be checked.\n   * @throws IOException\n   */\n  private void validatePath(Path path) throws IOException {\n    Path fPart = path.getParent();\n    do {\n      try {","sourceCodeStart":554,"sourceCodeEnd":590,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-tools/hadoop-aliyun/src/main/java/org/apache/hadoop/fs/aliyun/oss/AliyunOSSFileSystem.java#L554-L590","documentation":"Thrown by AliyunOSSFileSystem.mkdirs(): getFileStatus(path) succeeded and reported a file. A file object occupies the exact key where a directory (prefix) is requested, so mkdirs fails with FileAlreadyExistsException(\"Path is a file: \" + path). This mirrors HDFS behavior rather than silently converting.","triggerScenarios":"Calling fs.mkdirs(p) (often implicitly via OutputFormat setup or createNonRecursive flows) when an object exists at exactly that key as a file; e.g., mkdirs(oss://bucket/data) while 'data' is a zero-or-more-byte object.","commonSituations":"Schema/table layout changes turning a former file path into a partition directory; tools that created 'fake directory' files at the same key; concurrent writers where one writes a file and another tries to establish the directory.","solutions":["Remove or rename the file at the conflicting key (fs.delete(path) after confirming it is disposable), then retry mkdirs","Redesign the layout so names are exclusively files or directories, never both","If the 'file' is a stale marker, delete it with the OSS console/API and re-run"],"exampleFix":"// before\nfs.mkdirs(new Path(\"oss://bucket/data\")); // 'data' object exists\n\n// after\nPath p = new Path(\"oss://bucket/data\");\nif (fs.exists(p) && !fs.getFileStatus(p).isDirectory()) {\n  fs.delete(p, false);\n}\nfs.mkdirs(p);","handlingStrategy":"validation","validationCode":"if (fs.exists(path) && fs.getFileStatus(path).isFile()) {\n  throw new IOException(\"Cannot mkdirs: file occupies path \" + path);\n}\nfs.mkdirs(path);","typeGuard":null,"tryCatchPattern":"catch (FileAlreadyExistsException e) { /* path is a file: remove/rename it or change the directory layout */ throw e; }","preventionTips":["Check getFileStatus before mkdirs on paths that might hold files","Keep file and directory names disjoint in key layouts"],"tags":["aliyun-oss","mkdir","path-conflict","hadoop-connector"],"backgroundTag":"mkdir-path-is-file","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}