apache/hadoop · error · IllegalArgumentException

Passed URI's scheme is not for Hdfs

Error message

Passed URI's scheme is not for Hdfs

What it means

Hdfs is the AbstractFileSystem implementation (used via FileContext) for the hdfs:// scheme. Its constructor — invoked by AbstractFileSystem.createFileSystem from the fs.AbstractFileSystem.<scheme>.impl config mapping — asserts theUri.getScheme() equals "hdfs" (case-insensitively) and throws IllegalArgumentException otherwise, guarding against a scheme-to-implementation mapping mismatch.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/fs/Hdfs.java:84

  static {
    HdfsConfiguration.init();
  }

  /**
   * This constructor has the signature needed by
   * {@link AbstractFileSystem#createFileSystem(URI, Configuration)}
   * 
   * @param theUri which must be that of Hdfs
   * @param conf configuration
   * @throws IOException
   */
  Hdfs(final URI theUri, final Configuration conf) throws IOException, URISyntaxException {
    super(theUri, HdfsConstants.HDFS_URI_SCHEME, true,
        HdfsClientConfigKeys.DFS_NAMENODE_RPC_PORT_DEFAULT);

    if (!theUri.getScheme().equalsIgnoreCase(HdfsConstants.HDFS_URI_SCHEME)) {
      throw new IllegalArgumentException("Passed URI's scheme is not for Hdfs");
    }
    String host = theUri.getHost();
    if (host == null) {
      throw new IOException("Incomplete HDFS URI, no host: " + theUri);
    }

    this.dfs = new DFSClient(theUri, conf, getStatistics());
  }

  @Override
  public int getUriDefaultPort() {
    return HdfsClientConfigKeys.DFS_NAMENODE_RPC_PORT_DEFAULT;
  }

  @Override
  public HdfsDataOutputStream createInternal(Path f,
      EnumSet<CreateFlag> createFlag, FsPermission absolutePermission,
      int bufferSize, short replication, long blockSize, Progressable progress,

View on GitHub (pinned to 2add963021)

Solutions

1. Use hdfs:// URIs with this implementation
2. Audit core-site.xml: fs.AbstractFileSystem.hdfs.impl should map to org.apache.hadoop.fs.Hdfs, and every other scheme to its own impl class
3. For webhdfs://, use the WebHdfs AbstractFileSystem impl instead of routing the scheme at Hdfs

Example fix

<!-- before (core-site.xml) -->
<property>
  <name>fs.AbstractFileSystem.myproto.impl</name>
  <value>org.apache.hadoop.fs.Hdfs</value>
</property>

<!-- after -->
<property>
  <name>fs.AbstractFileSystem.hdfs.impl</name>
  <value>org.apache.hadoop.fs.Hdfs</value>
</property>

URI u = new URI("hdfs", "nn1", "/path", null);
if (!"hdfs".equalsIgnoreCase(u.getScheme())) {
  throw new IllegalArgumentException("need an hdfs:// URI, got: " + u);
}
FileContext fc = FileContext.getFileContext(u, conf);

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

try {
  AbstractFileSystem.createFileSystem(u, conf);
} catch (IllegalArgumentException e) {
  // scheme/impl mapping mismatch in fs.AbstractFileSystem.*.impl
}

When it happens

Trigger: A URI whose scheme is not hdfs is dispatched to this class: fs.AbstractFileSystem.<scheme>.impl mistakenly set to org.apache.hadoop.fs.Hdfs for another scheme (e.g. webhdfs or a custom one), or code constructing Hdfs directly with a file:// or other URI.

Common situations: Copy-paste errors in core-site.xml fs.AbstractFileSystem.*.impl entries; custom FileContext tooling that hardcodes the Hdfs class for any URI; confusing the FileContext impl namespace (fs.AbstractFileSystem.*) with the FileSystem one (fs.*.impl).

Related errors

• Incomplete HDFS URI, no host: {}
• Bad configuration of hadoop.security.key.provider.path at ${
• Uri without authority: {uri}
• Wrong FS: {path}, expected: {this.getUri()}
• No scheme in default FS: ${uri}

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