apache/hadoop · error · FileSystemException

Only HDFS is supported as underlyingFileSystem, fs scheme:{}

Error message

Only HDFS is supported as underlyingFileSystem, fs scheme:{} uri to be added{}

What it means

Nfs3Utils resolves the backing FileSystem URI for an export (including through mount-table entries) and then enforces that the final scheme is hdfs: the NFS gateway can only re-export HDFS. Any other scheme (file, s3a, viewfs-to-non-hdfs target, etc.) throws this FileSystemException during export registration.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-nfs/src/main/java/org/apache/hadoop/hdfs/nfs/nfs3/Nfs3Utils.java:268

    URI fsURI = fs.getUri();
    String scheme = fs.getScheme();
    if (scheme.equalsIgnoreCase(FsConstants.VIEWFS_SCHEME)) {
      ViewFileSystem viewFs = (ViewFileSystem)fs;
      ViewFileSystem.MountPoint[] mountPoints = viewFs.getMountPoints();
      for (ViewFileSystem.MountPoint mount : mountPoints) {
        String mountedPath = mount.getMountedOnPath().toString();
        if (exportPath.startsWith(mountedPath)) {
          String subpath = exportPath.substring(mountedPath.length());
          fsURI = mount.getTargetFileSystemURIs()[0].resolve(subpath);
          break;
        }
      }
    } else if (scheme.equalsIgnoreCase(HdfsConstants.HDFS_URI_SCHEME)) {
      fsURI = fsURI.resolve(exportPath);
    }

    if (!fsURI.getScheme().equalsIgnoreCase(HdfsConstants.HDFS_URI_SCHEME)) {
      throw new FileSystemException("Only HDFS is supported as underlying"
          + "FileSystem, fs scheme:" + scheme + " uri to be added" + fsURI);
    }
    return fsURI;
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Change the export entry to an explicit hdfs:// URI (hdfs://nameservice/path or hdfs://nn:8020/path).
2. If using viewfs, fix the mount table so every target that gets exported resolves to an hdfs authority.
3. Remove non-HDFS paths from nfs.exports — they cannot be served by this gateway.

Example fix

# before (nfs.exports)
/data rw              # resolves to file:///data via local defaultFS
# after
/data hdfs://ns1/data rw   # or set fs.defaultFS to the HDFS nameservice

/* validate the export URI scheme before registration */
URI u = URI.create(exportUri);
if (u.getScheme() == null || !u.getScheme().equalsIgnoreCase("hdfs")) {
    throw new IllegalArgumentException(
        "nfs.exports entry must use the hdfs scheme: " + exportUri);
}

private boolean isHdfsExportUri(URI u) {
    return u != null && "hdfs".equalsIgnoreCase(u.getScheme());
}

try {
    URI backing = Nfs3Utils.getWanRpcAddress... /* resolve export URI */;
} catch (FileSystemException e) {
    // deterministic: the message prints the offending scheme and URI.
    // Fail the export/config check at deploy time; do not retry.
}

When it happens

Trigger: An nfs.exports entry whose URI scheme is not hdfs://; a viewfs mount whose target file system resolves to a non-HDFS URI; a URI with no scheme that defaults to the local filesystem ('file'). The message prints the offending scheme and resolved URI.

Common situations: Trying to NFS-export a local directory or object-store path; using defaultFS-less relative export paths; mount-table entries added for non-HDFS backends that the gateway then tries to register.

Related errors

• FS:%s, Namenode ID collision for path:%s nnid:%s uri being a
• No namenode URI found for user:{} namenodeId:{}
• Can not create a Path from a null string
• Can not create a Path from an empty string
• no SharedFileDescriptorFactory paths were configured.

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