apache/hadoop · error · IllegalArgumentException

FileSystem {} is not an HDFS file system. The fs class is: {

Error message

FileSystem {} is not an HDFS file system. The fs class is: {}

What it means

All dfsadmin storage-admin subcommands funnel through AdminHelper.checkAndGetDFS, which must hand back a DistributedFileSystem. If the resolved FileSystem is any other implementation — LocalFileSystem for file://, S3A, etc. — it throws IllegalArgumentException('FileSystem <uri> is not an HDFS file system. The fs class is: <class>'). For a ViewFileSystemOverloadScheme it first resolves the raw child filesystem behind the -fs path (using FileSystem.getDefaultUri) and applies the same check to the child.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/AdminHelper.java:69

  static DistributedFileSystem getDFS(URI uri, Configuration conf)
      throws IOException {
    FileSystem fs = FileSystem.get(uri, conf);
    return checkAndGetDFS(fs, conf);
  }

  static DistributedFileSystem checkAndGetDFS(FileSystem fs, Configuration conf)
      throws IOException {
    if ((fs instanceof ViewFileSystemOverloadScheme)) {
      // With ViewFSOverloadScheme, the admin will pass -fs option with intended
      // child fs mount path. GenericOptionsParser would have set the given -fs
      // as FileSystem's defaultURI. So, we are using FileSystem.getDefaultUri
      // to use the given -fs path.
      fs = ((ViewFileSystemOverloadScheme) fs)
          .getRawFileSystem(new Path(FileSystem.getDefaultUri(conf)), conf);
    }
    if (!(fs instanceof DistributedFileSystem)) {
      throw new IllegalArgumentException("FileSystem " + fs.getUri()
          + " is not an HDFS file system. The fs class is: "
          + fs.getClass().getName());
    }
    return (DistributedFileSystem) fs;
  }

  /**
   * NN exceptions contain the stack trace as part of the exception message.
   * When it's a known error, pretty-print the error and squish the stack trace.
   */
  static String prettifyException(Exception e) {
    if (e.getLocalizedMessage() != null) {
      return e.getClass().getSimpleName() + ": "
          + e.getLocalizedMessage().split("\n")[0];
    } else if (e.getStackTrace() != null && e.getStackTrace().length > 0) {
      return e.getClass().getSimpleName() + " at " + e.getStackTrace()[0];
    } else {
      return e.getClass().getSimpleName();

View on GitHub (pinned to 2add963021)

Solutions

Pass the cluster URI explicitly: hdfs dfsadmin -fs hdfs://<nn-host>:<rpc-port> -report
Fix fs.defaultFS in core-site.xml to hdfs://<nn>:8020 (or the nameservice URI) and export HADOOP_CONF_DIR
For ViewFileSystemOverloadScheme, point -fs at the HDFS mount child so getRawFileSystem() resolves to DistributedFileSystem
Sanity-check first: hdfs getconf -confKey fs.defaultFS

Example fix

# before
$ hdfs dfsadmin -setSpaceQuota 1t /data
# IllegalArgumentException: FileSystem file:/ is not an HDFS file system. The fs class is: org.apache.hadoop.fs.LocalFileSystem

# after
$ hdfs dfsadmin -fs hdfs://nn1.example.com:8020 -setSpaceQuota 1t /data

Defensive patterns

Strategy: type-guard

Validate before calling

# shell pre-flight before any dfsadmin storage command
scheme=$(hdfs getconf -confKey fs.defaultFS)
case "$scheme" in hdfs://*) ;; *) echo "fs.defaultFS=$scheme is not HDFS" >&2; exit 2;; esac

Type guard

static boolean isHdfsAdminTarget(FileSystem fs, Configuration conf) throws IOException {
  if (fs instanceof ViewFileSystemOverloadScheme vfs) {
    fs = vfs.getRawFileSystem(new Path(FileSystem.getDefaultUri(conf)), conf);
  }
  return fs instanceof DistributedFileSystem;
}

Prevention

Export HADOOP_CONF_DIR with the cluster's core-site.xml on admin hosts
Pass -fs hdfs://<nn>:8020 explicitly in scripts instead of trusting the default FS
For ViewFS overload schemes, target -fs at the HDFS mount child path

When it happens

Trigger: Running `hdfs dfsadmin -setSpaceQuota ...` / -report / -setAcl etc. when fs.defaultFS is file:/// (default when no core-site.xml or HADOOP_CONF_DIR is on the classpath); passing -fs with a non-HDFS URI (view://, s3a://bucket); a ViewFS-overload scheme whose mount for the -fs path resolves to a non-HDFS child.

Common situations: Gateway/edge nodes or CI containers without the cluster's config; fs.defaultFS typo (hdfs://nn:8200 vs 8020); running admin commands against the wrong cluster after a config refresh; new ViewFS mounts where the admin path points at an object-store child.

Related errors

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