{"record":{"id":"31e118d20cccacd6","repo":"apache/hadoop","slug":"createsymlink-is-not-supported-in-viewhdfs","errorCode":null,"errorMessage":"createSymlink is not supported in ViewHDFS","messagePattern":"createSymlink is not supported in ViewHDFS","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/ViewDistributedFileSystem.java","lineNumber":940,"sourceCode":"  public FileStatus getFileStatus(final Path f)\n      throws AccessControlException, FileNotFoundException, IOException {\n    if (this.vfs == null) {\n      return super.getFileStatus(f);\n    }\n    return this.vfs.getFileStatus(f);\n  }\n\n  @SuppressWarnings(\"deprecation\")\n  @Override\n  public void createSymlink(final Path target, final Path link,\n      final boolean createParent) throws IOException {\n     // Regular DFS behavior\n    if (this.vfs == null) {\n      super.createSymlink(target, link, createParent);\n      return;\n    }\n\n    throw new UnsupportedOperationException(\n        \"createSymlink is not supported in ViewHDFS\");\n  }\n\n  @Override\n  public boolean supportsSymlinks() {\n    if (this.vfs == null) {\n      return super.supportsSymlinks();\n    }\n    // we can enabled later if we want to support symlinks.\n    return false;\n  }\n\n  @Override\n  public FileStatus getFileLinkStatus(final Path f) throws IOException {\n    if (this.vfs == null) {\n      return super.getFileLinkStatus(f);\n    }\n    ViewFileSystemOverloadScheme.MountPathInfo<FileSystem> mountPathInfo =","sourceCodeStart":922,"sourceCodeEnd":958,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/ViewDistributedFileSystem.java#L922-L958","documentation":"createSymlink on ViewDistributedFileSystem throws UnsupportedOperationException when running in mount-table mode (vfs != null): symlinks cannot be represented consistently across a federated namespace, so creation is blocked even if child filesystems support them, and supportsSymlinks() returns false. In fallback mode it delegates to plain DistributedFileSystem.","triggerScenarios":"Calling FileSystem.createSymlink(...) or FileContext.createSymlink on a ViewHDFS URI with a configured mount table.","commonSituations":"Porting symlink-using applications to ViewHDFS; deployment scripts creating convenience symlinks at the view root.","solutions":["Create the symlink directly on the underlying cluster filesystem hosting the link's parent directory","Replace symlinks with mount-table link entries","Feature-detect with supportsSymlinks() before attempting creation"],"exampleFix":"// before\nfs.createSymlink(target, link, false);\n\n// after\nif (fs instanceof ViewDistributedFileSystem\n    && !fs.supportsSymlinks()) {\n  DistributedFileSystem dfs = findChildDfs(fs);\n  dfs.createSymlink(target, link, false);\n} else {\n  fs.createSymlink(target, link, false);\n}","handlingStrategy":"validation","validationCode":"if (!fs.supportsSymlinks()) {\n  // viewfs mount mode: create the link on the child DFS instead\n  DistributedFileSystem dfs = findChildDfs(fs);\n  dfs.createSymlink(target, link, createParent);\n} else {\n  fs.createSymlink(target, link, createParent);\n}","typeGuard":"static boolean canCreateSymlink(FileSystem fs) {\n  return !(fs instanceof ViewDistributedFileSystem) || fs.supportsSymlinks();\n}","tryCatchPattern":"try {\n  fs.createSymlink(target, link, false);\n} catch (UnsupportedOperationException e) {\n  findChildDfs(fs).createSymlink(target, link, false);","preventionTips":["Always feature-detect with supportsSymlinks() before createSymlink","Prefer mount-table link entries over symlinks in federated namespaces"],"tags":["hdfs","viewfs","symlink","unsupported"],"backgroundTag":"symlink-unsupported","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}