{"record":{"id":"3f7afb6ec536f0de","repo":"apache/hadoop","slug":"the-scheme-is-not-hdfs-uri","errorCode":null,"errorMessage":"The scheme is not hdfs, uri={}","messagePattern":"The scheme is not hdfs, uri=(.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/client/HdfsUtils.java","lineNumber":54,"sourceCode":" */\n@InterfaceAudience.Public\n@InterfaceStability.Evolving\npublic class HdfsUtils {\n  public static final Logger LOG = LoggerFactory.getLogger(HdfsUtils.class);\n\n  /**\n   * Is the HDFS healthy?\n   * HDFS is considered as healthy if it is up and not in safemode.\n   *\n   * @param uri the HDFS URI.  Note that the URI path is ignored.\n   * @return true if HDFS is healthy; false, otherwise.\n   */\n  @SuppressWarnings(\"deprecation\")\n  public static boolean isHealthy(URI uri) {\n    //check scheme\n    final String scheme = uri.getScheme();\n    if (!HdfsConstants.HDFS_URI_SCHEME.equalsIgnoreCase(scheme)) {\n      throw new IllegalArgumentException(\"The scheme is not \"\n          + HdfsConstants.HDFS_URI_SCHEME + \", uri=\" + uri);\n    }\n\n    final Configuration conf = new Configuration();\n    //disable FileSystem cache\n    conf.setBoolean(String.format(\"fs.%s.impl.disable.cache\", scheme), true);\n    //disable client retry for rpc connection and rpc calls\n    conf.setBoolean(HdfsClientConfigKeys.Retry.POLICY_ENABLED_KEY, false);\n    conf.setInt(\n        CommonConfigurationKeysPublic.IPC_CLIENT_CONNECT_MAX_RETRIES_KEY, 0);\n\n    try (DistributedFileSystem fs =\n             (DistributedFileSystem) FileSystem.get(uri, conf)) {\n      final boolean safemode = fs.setSafeMode(SafeModeAction.SAFEMODE_GET);\n      if (LOG.isDebugEnabled()) {\n        LOG.debug(\"Is namenode in safemode? {}; uri={}\", safemode, uri);\n      }\n      return !safemode;","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/client/HdfsUtils.java#L36-L72","documentation":"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.","triggerScenarios":"HdfsUtils.isHealthy(new URI(\"webhdfs://nn:9870\")), viewfs://cluster, s3a://..., or a URI built from a bare 'host:port' string whose getScheme() is null.","commonSituations":"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.","solutions":["Pass an hdfs:// URI, e.g. hdfs://nameservice or hdfs://nn:8020.","Derive the probe URI from the NameNode RPC address and force the hdfs scheme.","For WebHDFS endpoints, use the HTTP JSON status/JMX endpoints instead of HdfsUtils.isHealthy."],"exampleFix":"// before\nboolean ok = HdfsUtils.isHealthy(new URI(\"nn1:8020\")); // scheme == null\n\n// after\nboolean ok = HdfsUtils.isHealthy(new URI(\"hdfs://nn1:8020\"));","handlingStrategy":"validation","validationCode":"if (!\"hdfs\".equalsIgnoreCase(uri.getScheme())) {\n  throw new IllegalArgumentException(\n      \"isHealthy needs an hdfs:// URI, got scheme: \" + uri.getScheme());\n}\nboolean healthy = HdfsUtils.isHealthy(uri);","typeGuard":null,"tryCatchPattern":"try {\n  healthy = HdfsUtils.isHealthy(uri);\n} catch (IllegalArgumentException e) {\n  // wrong scheme: normalize the probe URI instead of failing the check\n  URI hdfsUri = URI.create(\"hdfs://\" + uri.getHost() + \":\" + uri.getPort());\n  healthy = HdfsUtils.isHealthy(hdfsUri);\n}","preventionTips":["Normalize health-probe URIs to hdfs:// at monitoring config load time.","Do not feed scheme-less host:port strings into URI-based HDFS client APIs.","Use HTTP/JMX endpoints for WebHDFS-side health checks."],"tags":["hdfs","health-check","uri","filesystem-scheme"],"backgroundTag":"filesystem-uri-scheme-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}