apache/hadoop · error · IllegalArgumentException

'{}' is not an HDFS URI.

Error message

'{}' is not an HDFS URI.

What it means

The HdfsAdmin constructor resolves the given URI with FileSystem.get(uri, conf) and requires a DistributedFileSystem (a ViewFileSystemOverloadScheme is first unwrapped to its raw filesystem using FileSystem.getDefaultUri(conf)). Any other implementation — local, object store, WebHdfsFileSystem — cannot serve HDFS admin operations and the constructor throws IllegalArgumentException("'<uri>' is not an HDFS URI.").

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/client/HdfsAdmin.java:88

  final private DistributedFileSystem dfs;
  public static final FsPermission TRASH_PERMISSION = new FsPermission(
      FsAction.ALL, FsAction.ALL, FsAction.ALL, true);

  /**
   * Create a new HdfsAdmin client.
   *
   * @param uri the unique URI of the HDFS file system to administer
   * @param conf configuration
   * @throws IOException in the event the file system could not be created
   */
  public HdfsAdmin(URI uri, Configuration conf) throws IOException {
    FileSystem fs = FileSystem.get(uri, conf);
    if ((fs instanceof ViewFileSystemOverloadScheme)) {
      fs = ((ViewFileSystemOverloadScheme) fs)
          .getRawFileSystem(new Path(FileSystem.getDefaultUri(conf)), conf);
    }
    if (!(fs instanceof DistributedFileSystem)) {
      throw new IllegalArgumentException("'" + uri + "' is not an HDFS URI.");
    } else {
      dfs = (DistributedFileSystem)fs;
    }
  }

  /**
   * Set the namespace quota (count of files, directories, and sym links) for a
   * directory.
   *
   * @param src the path to set the quota for
   * @param quota the value to set for the quota
   * @throws IOException in the event of error
   */
  public void setQuota(Path src, long quota) throws IOException {
    dfs.setQuota(src, quota, HdfsConstants.QUOTA_DONT_SET);
  }

  /**

View on GitHub (pinned to 2add963021)

Solutions

1. Pass an hdfs:// URI (or the HA nameservice URI) of the cluster to administer.
2. Check fs.defaultFS and fs.<scheme>.impl bindings so FileSystem.get(uri, conf) returns a DistributedFileSystem.
3. For ViewFileSystemOverloadScheme deployments, ensure the default URI maps to an HDFS mount so getRawFileSystem resolves to a DistributedFileSystem.

Example fix

// before
HdfsAdmin admin = new HdfsAdmin(new URI("webhdfs://nn1:9870"), conf);

// after
HdfsAdmin admin = new HdfsAdmin(new URI("hdfs://nn1:8020"), conf);

URI u = new URI(adminUri);
if (!"hdfs".equalsIgnoreCase(u.getScheme())) {
  throw new IllegalArgumentException(
      "HdfsAdmin needs an hdfs:// URI, got: " + u);
}

public static boolean isAdministrableHdfsUri(URI uri, Configuration conf)
    throws IOException {
  FileSystem fs = FileSystem.get(uri, conf);
  if (fs instanceof ViewFileSystemOverloadScheme) {
    fs = ((ViewFileSystemOverloadScheme) fs)
        .getRawFileSystem(new Path(FileSystem.getDefaultUri(conf)), conf);
  }
  return fs instanceof DistributedFileSystem;
}

try {
  admin = new HdfsAdmin(uri, conf);
} catch (IllegalArgumentException e) {
  if (String.valueOf(e.getMessage()).contains("is not an HDFS URI")) {
    // configuration problem: fix the URI / fs bindings, do not retry
    throw new ConfigurationException("Point HdfsAdmin at hdfs://, got " + uri, e);
  }
  throw e;
}

When it happens

Trigger: new HdfsAdmin(new URI("file:///"), conf), s3a://bucket/path, or webhdfs://nn:9870 (WebHdfsFileSystem is not a DistributedFileSystem); a viewfs URI whose raw-filesystem lookup against the default URI does not resolve to HDFS.

Common situations: Admin tools built from a generic fs.defaultFS that points at local or an object store; using WebHDFS endpoints with HdfsAdmin; HA setups where the URI scheme does not match the configured fs.<scheme>.impl binding.

Related errors

• The scheme is not hdfs, uri={}
• unexpected URISyntaxException
• FileSystem {} is not a DFS.
• URI: {} is not in the expected format
• Undefined scheme for " + u

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