{"record":{"id":"752e4e2039c49299","repo":"apache/hadoop","slug":"path-is-a-file-752e4e","errorCode":null,"errorMessage":"Path is a file: {}","messagePattern":"Path is a file: (.+?)","errorType":"exception","errorClass":"FileAlreadyExistsException","httpStatus":null,"severity":"error","filePath":"hadoop-cloud-storage-project/hadoop-huaweicloud/src/main/java/org/apache/hadoop/fs/obs/OBSCommonUtils.java","lineNumber":720,"sourceCode":"   *\n   * @param owner the owner OBSFileSystem instance\n   * @param path  path to create\n   * @return true if a directory was created\n   * @throws FileAlreadyExistsException there is a file at the path specified\n   * @throws IOException                other IO problems\n   * @throws ObsException               on failures inside the OBS SDK\n   */\n  static boolean innerMkdirs(final OBSFileSystem owner, final Path path)\n      throws IOException, FileAlreadyExistsException, ObsException {\n    LOG.debug(\"Making directory: {}\", path);\n    FileStatus fileStatus;\n    try {\n      fileStatus = owner.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      Path fPart = path.getParent();\n      do {\n        try {\n          fileStatus = owner.getFileStatus(fPart);\n          if (fileStatus.isDirectory()) {\n            break;\n          }\n          if (fileStatus.isFile()) {\n            throw new FileAlreadyExistsException(\n                String.format(\"Can't make directory for path '%s'\"\n                    + \" since it is a file.\", fPart));\n          }\n        } catch (FileNotFoundException fnfe) {\n          LOG.debug(\"file {} not fount, but ignore.\", path);\n        }\n        fPart = fPart.getParent();","sourceCodeStart":702,"sourceCodeEnd":738,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-cloud-storage-project/hadoop-huaweicloud/src/main/java/org/apache/hadoop/fs/obs/OBSCommonUtils.java#L702-L738","documentation":"OBSCommonUtils.innerMkdirs starts by stat-ing the requested path; if a FILE already exists at exactly that path, it throws FileAlreadyExistsException('Path is a file: <path>'). OBS has no real directories — the connector refuses to overwrite a key with a directory marker, because that would destroy data. This mirrors HDFS mkdirs semantics where mkdir over an existing file also fails.","triggerScenarios":"mkdirs() on a path occupied by an existing object, e.g. object 'obs://b/logs' exists (a file) and code calls mkdirs('obs://b/logs'); mapreduce/Spark staging dirs colliding with a previously written file of the same name; file/dir type flips between runs (yesterday a file, today used as directory).","commonSituations":"Partition writers that sometimes write a file directly at the partition path and sometimes treat it as a directory; leftover files from crashed jobs blocking new directory creation; distcp copying a directory onto a destination that already has a file with the dir's name; case-insensitive-ish path typos colliding with existing keys.","solutions":["Pick a different path for the directory, or delete/rename the conflicting file first after confirming it is disposable.","Standardize your layout: never let the same key prefix be both a file and a directory across code paths.","Pre-check with fs.getFileStatus(path).isFile() before mkdirs and surface a clear error naming the file.","Clean stale outputs (mapreduce.output.fileoutputformat.outputdir) before job start instead of relying on mkdirs to overwrite."],"exampleFix":"// before\nfs.mkdirs(new Path(\"obs://mybucket/logs\")); // object 'logs' already exists as file\n\n// after\nPath p = new Path(\"obs://mybucket/logs\");\nif (fs.exists(p) && !fs.getFileStatus(p).isDirectory()) {\n  throw new IOException(p + \" exists as a FILE; move or delete it first\");\n}\nfs.mkdirs(p);","handlingStrategy":"validation","validationCode":"static void ensureMkdirsSafe(FileSystem fs, Path p) throws IOException {\n  if (fs.exists(p) && !fs.getFileStatus(p).isDirectory()) {\n    throw new FileAlreadyExistsException(\"cannot mkdirs over file \" + p);\n  }\n  fs.mkdirs(p);\n}","typeGuard":null,"tryCatchPattern":"try {\n  fs.mkdirs(path);\n} catch (FileAlreadyExistsException e) {\n  if (String.valueOf(e.getMessage()).startsWith(\"Path is a file:\")) {\n    throw new LayoutConflictException(\"file/dir conflict at \" + path + \" — relocate the object\", e);\n  }\n  throw e;\n}","preventionTips":["Enforce one layout rule: any key is only ever a file or only ever a directory prefix.","Clean stale job output dirs before submission.","Add layout linting (ancestor/descendant file checks) to CI for generated path schemas."],"tags":["obs","huaweicloud","mkdirs","file-conflict","file-already-exists"],"backgroundTag":"mkdir-file-conflict","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}