apache/hadoop · error · UnsupportedOperationException

checkaccess is not supported for HttpFs on {0}. Please check

Error message

checkaccess is not supported for HttpFs on {0}. Please check your fs.defaultFS configuration

What it means

FSOperations.FSAccess.execute() runs CHECKACCESS through DistributedFileSystem.access(path, mode); there is no generic FileSystem access-check API, so any other backing filesystem throws UnsupportedOperationException (HTTP 400 to REST clients). Note the metrics increment (incrOpsCheckAccess) only happens on the HDFS path, so failed calls are also uncounted.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/fs/http/server/FSOperations.java:2099

     */
    public FSAccess(String path, FsAction mode) {
      this.path = new Path(path);
      this.mode = mode;
    }

    /**
     * Executes the filesystem operation.
     * @param fs filesystem instance to use.
     * @throws IOException thrown if an IO error occurred.
     */
    @Override
    public Void execute(FileSystem fs) throws IOException {
      if (fs instanceof DistributedFileSystem) {
        DistributedFileSystem dfs = (DistributedFileSystem) fs;
        dfs.access(path, mode);
        HttpFSServerWebApp.get().getMetrics().incrOpsCheckAccess();
      } else {
        throw new UnsupportedOperationException("checkaccess is "
            + "not supported for HttpFs on " + fs.getClass()
            + ". Please check your fs.defaultFS configuration");
      }
      return null;
    }
  }

  /**
   * Executor that performs a setErasureCodingPolicy operation.
   */
  @InterfaceAudience.Private
  public static class FSSetErasureCodingPolicy
      implements FileSystemAccess.FileSystemExecutor<Void> {

    private Path path;
    private String policyName;

    public FSSetErasureCodingPolicy(String path, String policyName) {

View on GitHub (pinned to 2add963021)

Solutions

Set fs.defaultFS=hdfs://<nameservice> in the HttpFS server configuration and restart
If backing is intentionally non-HDFS, replace CHECKACCESS with an open/append probe or the store's own permission model
Use WebHDFS directly against the NameNode for access checks
Verify with curl that LISTSTATUS succeeds (gateway healthy) and only CHECKACCESS fails (capability gap), isolating the cause

Example fix

<!-- before: httpfs-site.xml -->
<property><name>fs.defaultFS</name><value>file:///</value></property>
<!-- after -->
<property><name>fs.defaultFS</name><value>hdfs://ns1</value></property>
<!-- restart HttpFS; CHECKACCESS then delegates to DFS access() -->

Defensive patterns

Strategy: try-catch

Type guard

static DistributedFileSystem asDfs(FileSystem fs) {
  return fs instanceof DistributedFileSystem ? (DistributedFileSystem) fs : null;
}

Try / catch

try {
  fs.access(path, FsAction.READ_WRITE);
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("not supported for HttpFs")) {
    // capability gap, not a denial: fall back to an existence probe
    return fs.exists(path);
  }
  throw e;
}

Prevention

Do not build authorization decisions on CHECKACCESS through gateways of unknown backing
Distinguish 400 'not supported' from real AccessControlException before failing users
Fix fs.defaultFS on the HttpFS server when HDFS access checks are required

When it happens

Trigger: Client sends op=CHECKACCESS with fsaction=N/A params via webhdfs:// while HttpFS's filesystem is not DistributedFileSystem.

Common situations: Authorization pre-checks in apps (can this user read/write this path) routed through an HttpFS gateway on object storage; test harness with local FS; fs.defaultFS missing in server config.

Related errors

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