apache/hadoop · error · UnsupportedOperationException

This API:{} cannot be supported without default cluster(that

Error message

This API:{} cannot be supported without default cluster(that is linkFallBack).

What it means

checkDefaultDFS throws UnsupportedOperationException when ViewDistributedFileSystem has no default cluster to fall back on (fs == null). Certain APIs are only meaningful against a default cluster; in overload-scheme ViewHDFS that default is supplied by the linkFallback mount entry. Without it, the API cannot run.

Source

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

    return vfs.create(f, permission, cflags, bufferSize, replication, blockSize,
        progress, checksumOpt);
  }

  void checkDFS(FileSystem fs, String methodName) {
    if (!(fs instanceof DistributedFileSystem)) {
      String msg = new StringBuilder("This API:").append(methodName)
          .append(" is specific to DFS. Can't run on other fs:")
          .append(fs.getUri()).toString();
      throw new UnsupportedOperationException(msg);
    }
  }

  void checkDefaultDFS(FileSystem fs, String methodName) {
    if (fs == null) {
      String msg = new StringBuilder("This API:").append(methodName).append(
          " cannot be supported without default cluster(that is linkFallBack).")
          .toString();
      throw new UnsupportedOperationException(msg);
    }
  }

  @Override
  // DFS specific API
  protected HdfsDataOutputStream primitiveCreate(Path f,
      FsPermission absolutePermission, EnumSet<CreateFlag> flag, int bufferSize,
      short replication, long blockSize, Progressable progress,
      Options.ChecksumOpt checksumOpt) throws IOException {
    if (this.vfs == null) {
      return super
          .primitiveCreate(f, absolutePermission, flag, bufferSize, replication,
              blockSize, progress, checksumOpt);
    }
    ViewFileSystemOverloadScheme.MountPathInfo<FileSystem> mountPathInfo =
        this.vfs.getMountPathInfo(f, getConf());
    checkDFS(mountPathInfo.getTargetFs(), "primitiveCreate");
    return ((DistributedFileSystem) mountPathInfo.getTargetFs())

View on GitHub (pinned to 2add963021)

Solutions

1. Add a linkFallback entry to the ViewFileSystemOverloadScheme mount table pointing at the default HDFS cluster, then reload the configuration
2. Or invoke the API directly on the intended cluster's DistributedFileSystem

// Detect missing fallback early: a ViewHDFS in mount mode with no default cluster
if (viewFs instanceof ViewDistributedFileSystem
    && !((ViewDistributedFileSystem) viewFs).getChildFileSystems().isEmpty()
    && noLinkFallbackConfigured(conf)) {
  throw new IllegalStateException(
      "no linkFallback default cluster configured for the view");
}

try {
  needsDefaultClusterApi(viewFs);
} catch (UnsupportedOperationException e) {
  if (e.getMessage() != null
      && e.getMessage().contains("without default cluster")) {
    // route the call to a concrete cluster's DistributedFileSystem
  } else {
    throw e;
  }
}

When it happens

Trigger: Using ViewHDFS (vfs != null) with a mount table that defines no linkFallback to a default HDFS cluster, then calling an API guarded by checkDefaultDFS that requires a default cluster.

Common situations: Mount-table XML missing the fallback entry; ops tooling assuming a default cluster exists as in classic fallback ViewFS; partial migration to the viewfs overload scheme.

Related errors

• This API:{} is specific to DFS. Can't run on other fs:{}
• No DFS available in child filesystems
• Could not initialize target File System for URI : {targetDir
• ViewFs: Non absolute mount name in config:{src}
• Path {nextInode.fullPath} already exists as link

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