What causes "Path is a file: {}" in apache/hadoop?

Most likely a caller mistake: pass the intended directory path, not a file path.

apache/hadoop · error · FileAlreadyExistsException

Path is a file: {}

Error message

Path is a file: {}

What it means

mkdirs(f) first stats f itself: if f already exists as a FILE it throws FileAlreadyExistsException('Path is a file: <f>'). If f already is a directory, mkdirs is idempotent and returns true, so the exception fires only when the exact target path is occupied by a file.

Source

Thrown at hadoop-cloud-storage-project/hadoop-cos/src/main/java/org/apache/hadoop/fs/cosn/CosNFileSystem.java:510

        } else {
          throw new FileAlreadyExistsException(String.format(
              "Can't make directory for path '%s', it is a file.", parent));
        }
      } catch (FileNotFoundException e) {
        LOG.debug("The Path: [{}] does not exist.", path);
      }
      parent = parent.getParent();
    } while (parent != null);
  }

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

    return mkDirRecursively(f, permission);
  }

  /**
   * Recursively create a directory.
   *
   * @param f          Absolute path to the directory.
   * @param permission Directory permissions. Permission does not work for
   *                   the CosN filesystem currently.
   * @return Return true if the creation was successful,  throw a IOException.
   * @throws IOException The specified path already exists or an error
   *                     creating the path.
   */

View on GitHub (pinned to 2add963021)

Solutions

Most likely a caller mistake: pass the intended directory path, not a file path.
If the file is stale, fs.delete(f, false) then fs.mkdirs(f).
Guard reusable utilities with a status check before mkdirs.

Example fix

// before
fs.mkdirs(new Path('/out/part-00000')); // FileAlreadyExistsException: Path is a file: /out/part-00000

// after
fs.mkdirs(new Path('/out')); // the directory level you actually want

Defensive patterns

Strategy: validation

Validate before calling

if (fs.exists(f)) {
  FileStatus st = fs.getFileStatus(f);
  if (st.isFile()) { throw new IllegalStateException('Target is already a file: ' + f); }
  // existing directory: mkdirs is a no-op success
}

Try / catch

try {
  fs.mkdirs(f);
} catch (FileAlreadyExistsException e) {
  // 'Path is a file: <f>' -> the exact target is occupied by a file
  if (allowReplace) { fs.delete(f, false); fs.mkdirs(f); } else { throw e; }
}

Prevention

Keep file and directory names in disjoint namespaces in your layouts
Check status before mkdirs in reusable utilities
Derive directory paths from config, never from a file path string

When it happens

Trigger: fs.mkdirs(p) where an object with key p already exists; hadoop fs -mkdir on a path that is a file; tools that mkdir an output directory whose name equals an already-written output file.

Common situations: Output directory name equals a previously written file name; Hive/Spark warehouse partition creation colliding with staged files; passing a file path where its parent directory was meant.

Related errors

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