apache/hadoop · error · FileAlreadyExistsException

Path is a file: {}

Error message

Path is a file: {}

What it means

mkdirs() throws FileAlreadyExistsException("Path is a file: ...") when the path to create already exists as a file/object. The Hadoop contract requires mkdirs over an existing file to fail (mkdirs over an existing directory returns true).

Source

Thrown at hadoop-cloud-storage-project/hadoop-tos/src/main/java/org/apache/hadoop/fs/tosfs/RawFileSystem.java:470

  @Override
  public Path getWorkingDirectory() {
    return workingDir;
  }

  @Override
  public void setWorkingDirectory(Path newDir) {
    this.workingDir = newDir;
  }

  @Override
  public boolean mkdirs(Path path, FsPermission permission) throws IOException {
    try {
      FileStatus fileStatus = innerFileStatus(path);
      if (fileStatus.isDirectory()) {
        return true;
      } else {
        throw new FileAlreadyExistsException("Path is a file: " + path);
      }
    } catch (FileNotFoundException e) {
      Path dir = makeQualified(path);
      validatePath(dir);
      fsOps.mkdirs(dir);
    }
    return true;
  }

  private void validatePath(Path path) throws IOException {
    Path parent = path.getParent();
    do {
      try {
        FileStatus fileStatus = innerFileStatus(parent);
        if (fileStatus.isDirectory()) {
          // If path exists and a directory, exit
          break;
        } else {

View on GitHub (pinned to 2add963021)

Solutions

1. Delete or rename the conflicting file object before creating the directory
2. Fix path construction so files and directories never share the same key
3. Check first: if (fs.exists(p) && fs.getFileStatus(p).isFile()) handle the collision explicitly

Example fix

// before
fs.mkdirs(new Path("/data/export")); // /data/export exists as a file -> exception

// after
Path p = new Path("/data/export");
if (fs.exists(p) && fs.getFileStatus(p).isFile()) { fs.delete(p, false); }
fs.mkdirs(p);

if (fs.exists(p)) {
  if (!fs.getFileStatus(p).isDirectory()) {
    throw new IllegalStateException("file occupies directory path: " + p);
  }
} else {
  fs.mkdirs(p);
}

try { fs.mkdirs(p); }
catch (FileAlreadyExistsException e) {
  // path occupied by a file: relocate or delete, then retry
}

When it happens

Trigger: fs.mkdirs(path) where innerFileStatus(path) resolves to an existing file object, e.g. an object 'data/part-0' was written and the job now tries mkdirs('data/part-0').

Common situations: Path scheme collisions between file outputs and directory outputs (writing a file where a directory is later expected); re-running pipelines after a partial failure left a file at the directory location; Hive/Spark partition paths that were previously written as files.

Related errors

• Can't make directory for path '%s', it is a file.
• Path is a file: {}
• Path is a file: {}
• Can't make directory for path '%s' since it is a file.
• {} is a directory

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