apache/hadoop · error · IllegalArgumentException

The scheme is not hdfs, uri={}

Error message

The scheme is not hdfs, uri={}

What it means

HdfsUtils.isHealthy(URI) is a cheap liveness probe that connects as an HDFS client and checks safemode status. As a precondition it requires the literal hdfs scheme (case-insensitive), because it configures client retry and caching keys under that scheme; any other scheme — webhdfs, viewfs, or null (scheme-less RPC address) — is rejected with IllegalArgumentException before any connection attempt.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/client/HdfsUtils.java:54

 */
@InterfaceAudience.Public
@InterfaceStability.Evolving
public class HdfsUtils {
  public static final Logger LOG = LoggerFactory.getLogger(HdfsUtils.class);

  /**
   * Is the HDFS healthy?
   * HDFS is considered as healthy if it is up and not in safemode.
   *
   * @param uri the HDFS URI.  Note that the URI path is ignored.
   * @return true if HDFS is healthy; false, otherwise.
   */
  @SuppressWarnings("deprecation")
  public static boolean isHealthy(URI uri) {
    //check scheme
    final String scheme = uri.getScheme();
    if (!HdfsConstants.HDFS_URI_SCHEME.equalsIgnoreCase(scheme)) {
      throw new IllegalArgumentException("The scheme is not "
          + HdfsConstants.HDFS_URI_SCHEME + ", uri=" + uri);
    }

    final Configuration conf = new Configuration();
    //disable FileSystem cache
    conf.setBoolean(String.format("fs.%s.impl.disable.cache", scheme), true);
    //disable client retry for rpc connection and rpc calls
    conf.setBoolean(HdfsClientConfigKeys.Retry.POLICY_ENABLED_KEY, false);
    conf.setInt(
        CommonConfigurationKeysPublic.IPC_CLIENT_CONNECT_MAX_RETRIES_KEY, 0);

    try (DistributedFileSystem fs =
             (DistributedFileSystem) FileSystem.get(uri, conf)) {
      final boolean safemode = fs.setSafeMode(SafeModeAction.SAFEMODE_GET);
      if (LOG.isDebugEnabled()) {
        LOG.debug("Is namenode in safemode? {}; uri={}", safemode, uri);
      }
      return !safemode;

View on GitHub (pinned to 2add963021)

Solutions

1. Pass an hdfs:// URI, e.g. hdfs://nameservice or hdfs://nn:8020.
2. Derive the probe URI from the NameNode RPC address and force the hdfs scheme.
3. For WebHDFS endpoints, use the HTTP JSON status/JMX endpoints instead of HdfsUtils.isHealthy.

Example fix

// before
boolean ok = HdfsUtils.isHealthy(new URI("nn1:8020")); // scheme == null

// after
boolean ok = HdfsUtils.isHealthy(new URI("hdfs://nn1:8020"));

if (!"hdfs".equalsIgnoreCase(uri.getScheme())) {
  throw new IllegalArgumentException(
      "isHealthy needs an hdfs:// URI, got scheme: " + uri.getScheme());
}
boolean healthy = HdfsUtils.isHealthy(uri);

try {
  healthy = HdfsUtils.isHealthy(uri);
} catch (IllegalArgumentException e) {
  // wrong scheme: normalize the probe URI instead of failing the check
  URI hdfsUri = URI.create("hdfs://" + uri.getHost() + ":" + uri.getPort());
  healthy = HdfsUtils.isHealthy(hdfsUri);
}

When it happens

Trigger: HdfsUtils.isHealthy(new URI("webhdfs://nn:9870")), viewfs://cluster, s3a://..., or a URI built from a bare 'host:port' string whose getScheme() is null.

Common situations: Monitoring code fed the NameNode RPC address without a scheme; configs where fs.defaultFS is viewfs or webhdfs; tests reusing arbitrary URIs for health probes.

Related errors

• '{}' is not an 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/3f7afb6ec536f0de. Report an issue: GitHub.