apache/hadoop · error · UnsupportedOperationException

getServerDefaults is not supported for HttpFs on {0}. Please

Error message

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

What it means

FSOperations.FSGetServerDefaults.execute() answers GETSERVERDEFAULTS from DistributedFileSystem.getServerDefaults(); the executor deliberately refuses to fall back to the generic FileSystem.getServerDefaults() and throws UnsupportedOperationException when the HttpFS backing filesystem is not HDFS (HTTP 400 at the REST layer). The intent is parity with WebHDFS, which only exposes DFS server defaults.

Source

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

     * Creates a getServerDefaults executor.
     */
    public FSGetServerDefaults() {
    }

    /**
     * Executes the filesystem operation.
     * @param fs filesystem instance to use.
     * @return A JSON string.
     * @throws IOException thrown if an IO error occurred.
     */
    @Override
    public String execute(FileSystem fs) throws IOException {
      FsServerDefaults sds = null;
      if (fs instanceof DistributedFileSystem) {
        DistributedFileSystem dfs = (DistributedFileSystem) fs;
        sds = dfs.getServerDefaults();
      } else {
        throw new UnsupportedOperationException("getServerDefaults is "
            + "not supported for HttpFs on " + fs.getClass()
            + ". Please check your fs.defaultFS configuration");
      }
      return JsonUtil.toJsonString(sds);
    }
  }

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

    private Path path;
    private FsAction mode;

    /**

View on GitHub (pinned to 2add963021)

Solutions

Configure the HttpFS server's fs.defaultFS to the HDFS nameservice and restart
Read defaults from the client-side configuration (conf.getLongBytes("dfs.blocksize", ...)) when the backing store is intentionally non-HDFS
Use WebHDFS against the NameNode for authoritative server defaults
Check the loaded httpfs-site.xml, not just core-site defaults on the host

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 so GETSERVERDEFAULTS returns FsServerDefaults JSON -->

Defensive patterns

Strategy: try-catch

Type guard

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

Try / catch

try {
  FsServerDefaults d = fs.getServerDefaults();
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("not supported for HttpFs")) {
    // fall back to client-side defaults when the gateway is not HDFS-backed
    return new FsServerDefaultsBuilder(conf).get();
  }
  throw e;
}

Prevention

Use this op as the cheap capability probe: GETSERVERDEFAULTS failing with 'not supported for HttpFs' marks the gateway non-HDFS
Cache server defaults at startup instead of fetching per operation
Prefer WebHDFS on the NameNode for authoritative defaults

When it happens

Trigger: Client sends op=GETSERVERDEFAULTS via webhdfs:// against HttpFS backed by file:/// or an object store; tools probing block-size/replication defaults through the gateway.

Common situations: Clients reading fs server defaults (block size, replication, write buffer) through an HttpFS URL; HttpFS server installed without HDFS config; gateway repurposed for non-HDFS storage.

Related errors

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