apache/hadoop · error · FileAlreadyExistsException

Path is a file: {path}

Error message

Path is a file: {path}

What it means

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.

Source

Thrown at hadoop-tools/hadoop-aliyun/src/main/java/org/apache/hadoop/fs/aliyun/oss/AliyunOSSFileSystem.java:572

    if (StringUtils.isNotEmpty(key)) {
      if (!key.endsWith("/")) {
        dirName += "/";
      }
      store.storeEmptyFile(dirName);
    }
    return true;
  }

  @Override
  public boolean mkdirs(Path path, FsPermission permission)
      throws IOException {
    try {
      FileStatus fileStatus = getFileStatus(path);

      if (fileStatus.isDirectory()) {
        return true;
      } else {
        throw new FileAlreadyExistsException("Path is a file: " + path);
      }
    } catch (FileNotFoundException e) {
      validatePath(path);
      String key = pathToKey(path);
      return mkdir(key);
    }
  }

  /**
   * Check whether the path is a valid path.
   *
   * @param path the path to be checked.
   * @throws IOException
   */
  private void validatePath(Path path) throws IOException {
    Path fPart = path.getParent();
    do {
      try {

View on GitHub (pinned to 2add963021)

Solutions

1. Remove or rename the file at the conflicting key (fs.delete(path) after confirming it is disposable), then retry mkdirs
2. Redesign the layout so names are exclusively files or directories, never both
3. If the 'file' is a stale marker, delete it with the OSS console/API and re-run

Example fix

// before
fs.mkdirs(new Path("oss://bucket/data")); // 'data' object exists

// after
Path p = new Path("oss://bucket/data");
if (fs.exists(p) && !fs.getFileStatus(p).isDirectory()) {
  fs.delete(p, false);
}
fs.mkdirs(p);

if (fs.exists(path) && fs.getFileStatus(path).isFile()) {
  throw new IOException("Cannot mkdirs: file occupies path " + path);
}
fs.mkdirs(path);

catch (FileAlreadyExistsException e) { /* path is a file: remove/rename it or change the directory layout */ throw e; }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• {path} is a directory
• Not a directory: {parent}
• Can't make directory for path '%s', it is a file.
• Mkdirs failed to create {} (exists={}, cwd={})
• Parent path is not a directory: {} {}

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/be72809e6d116a5a. Report an issue: GitHub.