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: {}

What it means

In InternalDirOfViewFs.createInternal, when a root fallback link exists, creation inside an internal dir is allowed to fall through to the fallback cluster — but only if the file name does not collide with an existing child of the internal dir. If theInternalDir.getChildren() contains f.getName() (i.e. a mount point with that name already exists under this dir), it throws FileAlreadyExistsException("A mount path(file/dir) already exist with the requested path: <childFullPath>") to keep the mount namespace and fallback namespace from diverging.

Source

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

    @Override
    public FSDataOutputStream createInternal(final Path f,
        final EnumSet<CreateFlag> flag, final FsPermission absolutePermission,
        final int bufferSize, final short replication, final long blockSize,
        final Progressable progress, final ChecksumOpt checksumOpt,
        final boolean createParent) throws AccessControlException,
        FileAlreadyExistsException, FileNotFoundException,
        ParentNotDirectoryException, UnsupportedFileSystemException,
        UnresolvedLinkException, 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);
        }

        AbstractFileSystem 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
              .createInternal(fileToCreate, flag, absolutePermission,
                  bufferSize, replication, blockSize, progress, checksumOpt,
                  true);
        } catch (IOException e) {
          StringBuilder msg =

View on GitHub (pinned to 2add963021)

Solutions

1. Choose a file/dir name that is not a configured mount point under that parent
2. Create the path on the backing cluster directly (bypass viewfs) if the collision is intentional
3. Remove or rename the conflicting mount-table entry (fs.viewfs.mounttable.<n>.link.<name>)

Example fix

// before: /data is a mount point and fallback exists
fc.create(new Path("viewfs:///data"), EnumSet.of(CreateFlag.CREATE)); // throws

// after: pick a non-conflicting name
fc.create(new Path("viewfs:///data_archive"), EnumSet.of(CreateFlag.CREATE));

static boolean nameCollidesWithMount(ViewFileSystem vfs, Path parent, Path file) {
  String child = file.getName();
  String ps = parent.isRoot() ? "" : parent.toUri().getPath();
  String candidate = (ps + "/" + child).replaceAll("//+", "/");
  return vfs.getMountPoints().stream()
      .anyMatch(mp -> mp.getMountedOnPath().toUri().getPath().equals(candidate));
}
// if (nameCollidesWithMount(vfs, parent, f)) choose another name before create

try {
  out = fc.create(f, EnumSet.of(CreateFlag.CREATE));
} catch (FileAlreadyExistsException fae) {
  if (fae.getMessage().contains("A mount path(file/dir) already exist")) { /* name shadows a mount point */ }
}

When it happens

Trigger: With fs.viewfs.mounttable.<n>.linkFallback set, creating viewfs:///data when /data is also a mount link under the same internal dir; writing via fallback into names that shadow mount points.

Common situations: Clusters that adopted linkFallback (HADOOP-16598) so tools can write anywhere, then tools create directories whose names equal configured mount points; ambiguous paths after mount-table updates.

Related errors

• / is not a file. The directory / already exist at: {}
• getXAttrs on path `{}' is not within a mount point
• listXAttrs on path `{}' is not within a mount point
• getQuotaUsage on path `{}' is not within a mount point
• getStoragePolicy on path `{}' is not within a mount point

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