apache/hadoop · error · UnsupportedOperationException

createSymlink is not supported in ViewHDFS

Error message

createSymlink is not supported in ViewHDFS

What it means

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.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/ViewDistributedFileSystem.java:940

  public FileStatus getFileStatus(final Path f)
      throws AccessControlException, FileNotFoundException, IOException {
    if (this.vfs == null) {
      return super.getFileStatus(f);
    }
    return this.vfs.getFileStatus(f);
  }

  @SuppressWarnings("deprecation")
  @Override
  public void createSymlink(final Path target, final Path link,
      final boolean createParent) throws IOException {
     // Regular DFS behavior
    if (this.vfs == null) {
      super.createSymlink(target, link, createParent);
      return;
    }

    throw new UnsupportedOperationException(
        "createSymlink is not supported in ViewHDFS");
  }

  @Override
  public boolean supportsSymlinks() {
    if (this.vfs == null) {
      return super.supportsSymlinks();
    }
    // we can enabled later if we want to support symlinks.
    return false;
  }

  @Override
  public FileStatus getFileLinkStatus(final Path f) throws IOException {
    if (this.vfs == null) {
      return super.getFileLinkStatus(f);
    }
    ViewFileSystemOverloadScheme.MountPathInfo<FileSystem> mountPathInfo =

View on GitHub (pinned to 2add963021)

Solutions

1. Create the symlink directly on the underlying cluster filesystem hosting the link's parent directory
2. Replace symlinks with mount-table link entries
3. Feature-detect with supportsSymlinks() before attempting creation

Example fix

// before
fs.createSymlink(target, link, false);

// after
if (fs instanceof ViewDistributedFileSystem
    && !fs.supportsSymlinks()) {
  DistributedFileSystem dfs = findChildDfs(fs);
  dfs.createSymlink(target, link, false);
} else {
  fs.createSymlink(target, link, false);
}

if (!fs.supportsSymlinks()) {
  // viewfs mount mode: create the link on the child DFS instead
  DistributedFileSystem dfs = findChildDfs(fs);
  dfs.createSymlink(target, link, createParent);
} else {
  fs.createSymlink(target, link, createParent);
}

static boolean canCreateSymlink(FileSystem fs) {
  return !(fs instanceof ViewDistributedFileSystem) || fs.supportsSymlinks();
}

try {
  fs.createSymlink(target, link, false);
} catch (UnsupportedOperationException e) {
  findChildDfs(fs).createSymlink(target, link, false);

When it happens

Trigger: Calling FileSystem.createSymlink(...) or FileContext.createSymlink on a ViewHDFS URI with a configured mount table.

Common situations: Porting symlink-using applications to ViewHDFS; deployment scripts creating convenience symlinks at the view root.

Related errors

• No DFS available in child file systems.
• No DFS found in child fs. This API can't be supported in non
• Filesystem does not support symlinks!
• Operation not supported
• Not able to initialize fs in getDefaultBlockSize for path <

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