apache/hadoop · error · FileAlreadyExistsException

Path {nextInode.fullPath} already exists as link

Error message

Path {nextInode.fullPath} already exists as link

What it means

While inserting a mount, InodeTree walks the source path components. If an intermediate component already resolves to a link and the file system does not support nested mounts (isNestedMountPointSupported=false), it throws FileAlreadyExistsException('Path <path> already exists as link'). With nested-mount support the tree instead wraps the existing link in an INodeDirLink.

Source

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

    int i;
    // Ignore first initial slash, process all except last component
    for (i = 1; i < srcPaths.length - 1; i++) {
      final String iPath = srcPaths[i];
      INode<T> nextInode = curInode.resolveInternal(iPath);
      if (nextInode == null) {
        INodeDir<T> newDir = curInode.addDir(iPath, aUgi);
        newDir.setInternalDirFs(getTargetFileSystem(newDir));
        nextInode = newDir;
      }
      if (!nextInode.isInternalDir()) {
        if (isNestedMountPointSupported) {
          // nested mount detected, add a new INodeDirLink that wraps existing INodeLink to INodeTree and override existing INodelink
          INodeDirLink<T> dirLink = new INodeDirLink<T>(nextInode.fullPath, aUgi, (INodeLink<T>) nextInode);
          curInode.addDirLink(iPath, dirLink);
          curInode = dirLink;
        } else {
          // Error - expected a dir but got a link
          throw new FileAlreadyExistsException("Path " + nextInode.fullPath +
              " already exists as link");
        }
      } else {
        assert(nextInode.isInternalDir());
        curInode = (INodeDir<T>) nextInode;
      }
    }

    // Now process the last component
    // Add the link in 2 cases: does not exist or a link exists
    String iPath = srcPaths[i];// last component
    if (curInode.resolveInternal(iPath) != null) {
      //  directory/link already exists
      StringBuilder strB = new StringBuilder(srcPaths[0]);
      for (int j = 1; j <= i; ++j) {
        strB.append('/').append(srcPaths[j]);
      }
      throw new FileAlreadyExistsException("Path " + strB +

View on GitHub (pinned to 2add963021)

Solutions

1. Remove or restructure overlapping mounts so no mount source sits under another mount
2. Use a Hadoop build/config where nested mount points are supported (isNestedMountPointSupported=true)
3. Replace the parent single link with linkMerge so children remain resolvable

Example fix

<!-- before: /user/data nested under mounted /user -->
<property><name>fs.viewfs.mounttable.cluster.link./user</name>
  <value>hdfs://nnA/user</value></property>
<property><name>fs.viewfs.mounttable.cluster.link./user/data</name>
  <value>hdfs://nnB/data</value></property>

<!-- after: single mount; data reached through nnA -->
<property><name>fs.viewfs.mounttable.cluster.link./user</name>
  <value>hdfs://nnA/user</value></property>

static boolean hasNestedMounts(Collection<String> srcs) {
  List<String> sorted = new ArrayList<>(srcs);
  Collections.sort(sorted);
  for (int i = 1; i < sorted.size(); i++) {
    if (sorted.get(i).startsWith(sorted.get(i - 1) + "/")) {
      return true;
    }
  }
  return false;
}

Catch FileAlreadyExistsException at ViewFileSystem init; 'already exists as link' identifies an overlapping mount — sort the mount sources and remove or restructure the nested one.

When it happens

Trigger: Two mount entries where one source is a prefix of the other — e.g. link./user=... and link./user/data=... — on a ViewFileSystem built without nested mount support.

Common situations: Growing a federation mount table over time until mounts overlap; merging mount tables from two clusters; adding sub-directory mounts beneath existing mounts.

Related errors

• Path {strB} already exists as dir; cannot create link here
• ViewFs: Non absolute mount name in config:{src}
• Unexpected mount table link entry '{key}'. Use linkMergeSlas
• ViewFs: Cannot initialize: Invalid entry in Mount table in c
• getServerDefaults on empty path is invalid

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