apache/hadoop · error · FileAlreadyExistsException

A mount path(file/dir) already exist with the requested path

Error message

A mount path(file/dir) already exist with the requested path: <fullPath>

What it means

When a mount table defines a root fallback link (linkFallback), ViewFileSystem.InternalDir.create(...) forwards creates at internal directories to the fallback file system. It first checks the children of the internal dir: if the file name being created collides with an existing mount point name, it throws FileAlreadyExistsException('A mount path(file/dir) already exist with the requested path: <fullPath>') because the mount entry shadows the fallback file.

Source

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

      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);

        try {
          return linkedFallbackFs
              .create(fileToCreate, permission, overwrite, bufferSize,
                  replication, blockSize, progress);
        } catch (IOException e) {
          LOG.error("Failed to create file: {} at fallback: {}", fileToCreate,
              linkedFallbackFs.getUri(), e);

View on GitHub (pinned to 2add963021)

Solutions

  1. Write the file under a different leaf name that does not collide with a mount point name
  2. Restructure the mount table so application file names and mount point names do not share the internal directory's namespace
  3. Mount that exact path explicitly (turn it into a real target) instead of relying on the fallback
  4. Pre-check theInternalDir children indirectly: attempt fs.getFileStatus(new Path(parent, leaf)) and treat an existing dir/mount as a naming conflict before create

Example fix

// before: /data/hdfs is a mount, create("/data/hdfs") with linkFallback -> FileAlreadyExistsException
FSDataOutputStream out = fs.create(new Path("/data/hdfs"));

// after: choose a non-colliding name or write inside the mount
FSDataOutputStream out = fs.create(new Path("/data/hdfs/newfile"));
// or rename the mount in core-site.xml if the name is required for the file
Defensive patterns

Strategy: validation

Validate before calling

// Detect leaf-name collision with a mount point before create
Path parent = f.getParent();
if (fs.exists(new Path(parent, f.getName()))
    && fs.getFileStatus(new Path(parent, f.getName())).isDirectory()) {
  throw new IOException(f.getName() + " collides with a mount point under " + parent);
}
FSDataOutputStream out = fs.create(f);

Try / catch

try {
  out = fs.create(f);
} catch (FileAlreadyExistsException e) {
  // leaf name equals a mount name in an internal dir with linkFallback
  out = fs.create(new Path(parent, f.getName() + ".data"));
}

Prevention

When it happens

Trigger: linkFallback is configured and the code creates a file directly at an internal directory whose leaf name equals an existing child mount, e.g. mounts define /data/hdfs and the create targets /data with fallback semantics; a merge-like layout where mount names occupy names the application also wants to use as file names.

Common situations: Federation mount tables mixing link, linkMerge and linkFallback entries; applications ported from plain HDFS that legitimately created files with names that later became mount point names; mount-table refactors that turned former data dirs into mount names.

Related errors

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