apache/hadoop · error · UnsupportedFileSystemException

Unexpected mount table link entry '{key}'. Use linkMergeSlas

Error message

Unexpected mount table link entry '{key}'. Use linkMergeSlash instead!

What it means

At mount-table load time, InodeTree special-cases the root: a single link whose source is '/' (from a key like fs.viewfs.mounttable.<name>.link./) is rejected with UnsupportedFileSystemException telling you to use linkMergeSlash. Mounting another filesystem at '/' must be a merge link so the root stays coherent.

Source

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

    final String linkMergePrefix = Constants.CONFIG_VIEWFS_LINK_MERGE + ".";
    final String linkMergeSlashPrefix =
        Constants.CONFIG_VIEWFS_LINK_MERGE_SLASH;
    boolean gotMountTableEntry = false;
    final UserGroupInformation ugi = UserGroupInformation.getCurrentUser();
    for (Entry<String, String> si : config) {
      final String key = si.getKey();
      if (!key.startsWith(mountTablePrefix)) {
        continue;
      }

      gotMountTableEntry = true;
      LinkType linkType;
      String src = key.substring(mountTablePrefix.length());
      String settings = null;
      if (src.startsWith(linkPrefix)) {
        src = src.substring(linkPrefix.length());
        if (src.equals(SlashPath.toString())) {
          throw new UnsupportedFileSystemException("Unexpected mount table "
              + "link entry '" + key + "'. Use "
              + Constants.CONFIG_VIEWFS_LINK_MERGE_SLASH  + " instead!");
        }
        linkType = LinkType.SINGLE;
      } else if (src.startsWith(linkFallbackPrefix)) {
        checkMntEntryKeyEqualsTarget(src, linkFallbackPrefix);
        linkType = LinkType.SINGLE_FALLBACK;
      } else if (src.startsWith(linkMergePrefix)) { // A merge link
        src = src.substring(linkMergePrefix.length());
        linkType = LinkType.MERGE;
      } else if (src.startsWith(linkMergeSlashPrefix)) {
        // This is a LinkMergeSlash entry. This entry should
        // not have any additional source path.
        checkMntEntryKeyEqualsTarget(src, linkMergeSlashPrefix);
        linkType = LinkType.MERGE_SLASH;
      } else if (src.startsWith(Constants.CONFIG_VIEWFS_LINK_NFLY)) {
        // prefix.settings.src
        src = src.substring(Constants.CONFIG_VIEWFS_LINK_NFLY.length() + 1);

View on GitHub (pinned to 2add963021)

Solutions

1. Replace the entry with fs.viewfs.mounttable.<name>.linkMergeSlash = <target-uri>
2. Note that once a merge-slash link is set, later regular links are rejected — mount specific paths via the merged namespace instead

Example fix

<!-- before -->
<property><name>fs.viewfs.mounttable.default.link./</name>
  <value>hdfs://nnOld/</value></property>

<!-- after -->
<property><name>fs.viewfs.mounttable.default.linkMergeSlash</name>
  <value>hdfs://nnOld/</value></property>

static boolean hasIllegalRootLink(Map<String, String> mountTable) {
  return mountTable.keySet().stream().anyMatch(k -> k.endsWith(".link./"));
}

Catch UnsupportedFileSystemException at ViewFileSystem init; the message itself directs the fix (use linkMergeSlash), so rewrite the key and re-initialize.

When it happens

Trigger: Configuring fs.viewfs.mounttable.<name>.link./ = <target-uri> in core-site.xml; typical when migrating a cluster to federation by mounting the old root.

Common situations: First-time ViewFs setups following legacy documentation; federation migrations that copy a plain link line for the root.

Related errors

• ViewFs: Non absolute mount name in config:{src}
• Path {nextInode.fullPath} already exists as link
• Path {strB} already exists as dir; cannot create link here
• 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/ec6ac8f045cb6fe7. Report an issue: GitHub.