{"record":{"id":"1634e1b2ded85b70","repo":"apache/hadoop","slug":"is-not-an-hdfs-uri","errorCode":null,"errorMessage":"'{}' is not an HDFS URI.","messagePattern":"'(.+?)' is not an 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/HdfsAdmin.java","lineNumber":88,"sourceCode":"  final private DistributedFileSystem dfs;\n  public static final FsPermission TRASH_PERMISSION = new FsPermission(\n      FsAction.ALL, FsAction.ALL, FsAction.ALL, true);\n\n  /**\n   * Create a new HdfsAdmin client.\n   *\n   * @param uri the unique URI of the HDFS file system to administer\n   * @param conf configuration\n   * @throws IOException in the event the file system could not be created\n   */\n  public HdfsAdmin(URI uri, Configuration conf) throws IOException {\n    FileSystem fs = FileSystem.get(uri, conf);\n    if ((fs instanceof ViewFileSystemOverloadScheme)) {\n      fs = ((ViewFileSystemOverloadScheme) fs)\n          .getRawFileSystem(new Path(FileSystem.getDefaultUri(conf)), conf);\n    }\n    if (!(fs instanceof DistributedFileSystem)) {\n      throw new IllegalArgumentException(\"'\" + uri + \"' is not an HDFS URI.\");\n    } else {\n      dfs = (DistributedFileSystem)fs;\n    }\n  }\n\n  /**\n   * Set the namespace quota (count of files, directories, and sym links) for a\n   * directory.\n   *\n   * @param src the path to set the quota for\n   * @param quota the value to set for the quota\n   * @throws IOException in the event of error\n   */\n  public void setQuota(Path src, long quota) throws IOException {\n    dfs.setQuota(src, quota, HdfsConstants.QUOTA_DONT_SET);\n  }\n\n  /**","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/client/HdfsAdmin.java#L70-L106","documentation":"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.\").","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass an hdfs:// URI (or the HA nameservice URI) of the cluster to administer.","Check fs.defaultFS and fs.<scheme>.impl bindings so FileSystem.get(uri, conf) returns a DistributedFileSystem.","For ViewFileSystemOverloadScheme deployments, ensure the default URI maps to an HDFS mount so getRawFileSystem resolves to a DistributedFileSystem."],"exampleFix":"// before\nHdfsAdmin admin = new HdfsAdmin(new URI(\"webhdfs://nn1:9870\"), conf);\n\n// after\nHdfsAdmin admin = new HdfsAdmin(new URI(\"hdfs://nn1:8020\"), conf);","handlingStrategy":"type-guard","validationCode":"URI u = new URI(adminUri);\nif (!\"hdfs\".equalsIgnoreCase(u.getScheme())) {\n  throw new IllegalArgumentException(\n      \"HdfsAdmin needs an hdfs:// URI, got: \" + u);\n}","typeGuard":"public static boolean isAdministrableHdfsUri(URI uri, Configuration conf)\n    throws IOException {\n  FileSystem fs = FileSystem.get(uri, conf);\n  if (fs instanceof ViewFileSystemOverloadScheme) {\n    fs = ((ViewFileSystemOverloadScheme) fs)\n        .getRawFileSystem(new Path(FileSystem.getDefaultUri(conf)), conf);\n  }\n  return fs instanceof DistributedFileSystem;\n}","tryCatchPattern":"try {\n  admin = new HdfsAdmin(uri, conf);\n} catch (IllegalArgumentException e) {\n  if (String.valueOf(e.getMessage()).contains(\"is not an HDFS URI\")) {\n    // configuration problem: fix the URI / fs bindings, do not retry\n    throw new ConfigurationException(\"Point HdfsAdmin at hdfs://, got \" + uri, e);\n  }\n  throw e;\n}","preventionTips":["Build HdfsAdmin from the cluster's hdfs:// (or HA nameservice) URI, never from fs.defaultFS blindly.","In tests, assert the URI scheme before constructing admin clients.","Remember WebHDFS URIs are rejected — HdfsAdmin is an hdfs:// client API."],"tags":["hdfs","admin","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"}