What causes "/ is not a file. The directory / already exist at: " in apache/hadoop?

Create the file under a mounted path, e.g. /data/hdfs/ instead of /data/

apache/hadoop · error · FileAlreadyExistsException

/ is not a file. The directory / already exist at: <theInter

Error message

/ is not a file. The directory / already exist at: <theInternalDir.fullPath>

What it means

ViewFileSystem.InternalDir.create(...) is the target FileSystem for mount-table internal directories. When the create path after resolution is exactly the internal directory itself (remaining path equals '/'), creating a file there is impossible because that 'file' is the mount-table directory; the code throws FileAlreadyExistsException('/ is not a file. The directory / already exist at: <internalPath>').

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/viewfs/ViewFileSystem.java:1455

    public void setWorkingDirectory(final Path new_dir) {
      throw new RuntimeException(
          "Internal impl error: getWorkingDir should not have been called");
    }

    @Override
    public FSDataOutputStream append(final Path f, final int bufferSize,
        final Progressable progress) throws IOException {
      throw readOnlyMountTable("append", f);
    }

    @Override
    public FSDataOutputStream create(final Path f,
        final FsPermission permission, final boolean overwrite,
        final int bufferSize, final short replication, final long blockSize,
        final Progressable progress) throws IOException {
      Preconditions.checkNotNull(f, "File cannot be null.");
      if (InodeTree.SlashPath.equals(f)) {
        throw new FileAlreadyExistsException(
            "/ is not a file. The directory / already exist at: "
                + theInternalDir.fullPath);
      }

      if (this.fsState.getRootFallbackLink() != null) {

        if (theInternalDir.getChildren().containsKey(f.getName())) {
          throw new FileAlreadyExistsException(
              "A mount path(file/dir) already exist with the requested path: "
                  + theInternalDir.getChildren().get(f.getName()).fullPath);
        }

        FileSystem linkedFallbackFs =
            this.fsState.getRootFallbackLink().getTargetFileSystem();
        Path parent = Path.getPathWithoutSchemeAndAuthority(
            new Path(theInternalDir.fullPath));
        String leaf = f.getName();
        Path fileToCreate = new Path(parent, leaf);

View on GitHub (pinned to 2add963021)

Solutions

Create the file under a mounted path, e.g. /data/hdfs/<file> instead of /data/<file>
Mount the directory itself: add fs.viewfs.mounttable.default.link.data=hdfs://nameservice1/data so it is a real target, not an internal dir
Configure a linkFallback for the internal dir so creates fall through to a backing cluster
Before creating, check fs.getFileStatus(dir).isDirectory() and fail with a clear message when the target is a mount-table directory

Example fix

// before
FSDataOutputStream out = fs.create(new Path("/data")); // /data is an internal dir -> throws

// after
if (fs.getFileStatus(new Path("/data")).isDirectory()) {
  throw new IOException("refusing to create file at mount-table directory /data");
}
FSDataOutputStream out = fs.create(new Path("/data/hdfs/report.csv")); // mounted child

Defensive patterns

Strategy: validation

Validate before calling

// Refuse to create at a directory path
if (fs.exists(f) && fs.getFileStatus(f).isDirectory()) {
  throw new IOException(f + " is a mount-table directory; cannot create file there");
}
FSDataOutputStream out = fs.create(f);

Try / catch

try {
  out = fs.create(f);
} catch (FileAlreadyExistsException e) {
  // f resolved to an internal mount-table dir; redirect under a mounted child
  out = fs.create(new Path(f, "part-0000"));
}

Prevention

Always create files as leaf paths under mounted directories
Validate output-dir configuration at job setup, not at first write
Mount (or linkFallback) any directory applications must write into directly

When it happens

Trigger: Creating a file whose viewfs path resolves to a mount-table-only directory, e.g. create('/data') when /data is only a parent of mounts (only /data/hdfs linked), or create('/') on a non-merge-slash mount table; writers that build the output path by stripping one component too many.

Common situations: Output/staging configuration pointing at the mount-table root instead of a mounted child; tools that derive 'parent + filename' where the parent is an internal dir; viewfs cutovers where /data became virtual but jobs still write directly to /data.

Related errors

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