{"record":{"id":"ec6ac8f045cb6fe7","repo":"apache/hadoop","slug":"unexpected-mount-table-link-entry-key-use-lin","errorCode":null,"errorMessage":"Unexpected mount table link entry '{key}'. Use linkMergeSlash instead!","messagePattern":"Unexpected mount table link entry '(.+?)'\\. Use linkMergeSlash instead!","errorType":"validation","errorClass":"UnsupportedFileSystemException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/viewfs/InodeTree.java","lineNumber":654,"sourceCode":"    final String linkMergePrefix = Constants.CONFIG_VIEWFS_LINK_MERGE + \".\";\n    final String linkMergeSlashPrefix =\n        Constants.CONFIG_VIEWFS_LINK_MERGE_SLASH;\n    boolean gotMountTableEntry = false;\n    final UserGroupInformation ugi = UserGroupInformation.getCurrentUser();\n    for (Entry<String, String> si : config) {\n      final String key = si.getKey();\n      if (!key.startsWith(mountTablePrefix)) {\n        continue;\n      }\n\n      gotMountTableEntry = true;\n      LinkType linkType;\n      String src = key.substring(mountTablePrefix.length());\n      String settings = null;\n      if (src.startsWith(linkPrefix)) {\n        src = src.substring(linkPrefix.length());\n        if (src.equals(SlashPath.toString())) {\n          throw new UnsupportedFileSystemException(\"Unexpected mount table \"\n              + \"link entry '\" + key + \"'. Use \"\n              + Constants.CONFIG_VIEWFS_LINK_MERGE_SLASH  + \" instead!\");\n        }\n        linkType = LinkType.SINGLE;\n      } else if (src.startsWith(linkFallbackPrefix)) {\n        checkMntEntryKeyEqualsTarget(src, linkFallbackPrefix);\n        linkType = LinkType.SINGLE_FALLBACK;\n      } else if (src.startsWith(linkMergePrefix)) { // A merge link\n        src = src.substring(linkMergePrefix.length());\n        linkType = LinkType.MERGE;\n      } else if (src.startsWith(linkMergeSlashPrefix)) {\n        // This is a LinkMergeSlash entry. This entry should\n        // not have any additional source path.\n        checkMntEntryKeyEqualsTarget(src, linkMergeSlashPrefix);\n        linkType = LinkType.MERGE_SLASH;\n      } else if (src.startsWith(Constants.CONFIG_VIEWFS_LINK_NFLY)) {\n        // prefix.settings.src\n        src = src.substring(Constants.CONFIG_VIEWFS_LINK_NFLY.length() + 1);","sourceCodeStart":636,"sourceCodeEnd":672,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/viewfs/InodeTree.java#L636-L672","documentation":"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.","triggerScenarios":"Configuring fs.viewfs.mounttable.<name>.link./ = <target-uri> in core-site.xml; typical when migrating a cluster to federation by mounting the old root.","commonSituations":"First-time ViewFs setups following legacy documentation; federation migrations that copy a plain link line for the root.","solutions":["Replace the entry with fs.viewfs.mounttable.<name>.linkMergeSlash = <target-uri>","Note that once a merge-slash link is set, later regular links are rejected — mount specific paths via the merged namespace instead"],"exampleFix":"<!-- before -->\n<property><name>fs.viewfs.mounttable.default.link./</name>\n  <value>hdfs://nnOld/</value></property>\n\n<!-- after -->\n<property><name>fs.viewfs.mounttable.default.linkMergeSlash</name>\n  <value>hdfs://nnOld/</value></property>","handlingStrategy":"validation","validationCode":"static boolean hasIllegalRootLink(Map<String, String> mountTable) {\n  return mountTable.keySet().stream().anyMatch(k -> k.endsWith(\".link./\"));\n}","typeGuard":null,"tryCatchPattern":"Catch UnsupportedFileSystemException at ViewFileSystem init; the message itself directs the fix (use linkMergeSlash), so rewrite the key and re-initialize.","preventionTips":["Never configure link./ for the root","Use linkMergeSlash exactly once per mount table","Validate federation config with a checklist before rollout"],"tags":["hadoop","viewfs","mount-table","configuration","root-mount"],"backgroundTag":"viewfs-invalid-mount-point","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}