apache/hadoop · error · UnsupportedOperationException

getSnapshotDiffListing is not supported for HttpFs on {0}. P

Error message

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

What it means

FSOperations.FSGetSnapshotDiffListing.execute() implements the paged GETSNAPSHOTDIFFLISTING via DistributedFileSystem.getSnapshotDiffReportListing() only; no generic FileSystem equivalent exists. On a non-HDFS backing filesystem the executor throws UnsupportedOperationException (HTTP 400 at the REST layer), pointing at the HttpFS server's fs.defaultFS configuration.

Source

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

    }

    /**
     * Executes the filesystem operation.
     *
     * @param fs filesystem instance to use.
     * @return A serialized JSON string of snapshot diffs.
     * @throws IOException thrown if an IO error occurred.
     */
    @Override
    public String execute(FileSystem fs) throws IOException {
      SnapshotDiffReportListing snapshotDiffReportListing = null;
      if (fs instanceof DistributedFileSystem) {
        DistributedFileSystem dfs = (DistributedFileSystem) fs;
        snapshotDiffReportListing =
            dfs.getSnapshotDiffReportListing(path, oldSnapshotName, snapshotName,
                snapshotDiffStartPath, snapshotDiffIndex);
      } else {
        throw new UnsupportedOperationException("getSnapshotDiffListing is not "
            + "supported for HttpFs on " + fs.getClass()
            + ". Please check your fs.defaultFS configuration");
      }
      if (snapshotDiffReportListing != null) {
        return JsonUtil.toJsonString(snapshotDiffReportListing);
      } else {
        return "";
      }
    }
  }

  /**
   *  Executor that performs a getSnapshottableDirListing operation.
   */
  @InterfaceAudience.Private
  public static class FSGetSnapshottableDirListing implements
      FileSystemAccess.FileSystemExecutor<String> {

View on GitHub (pinned to 2add963021)

Solutions

Point the HttpFS server's fs.defaultFS at HDFS (hdfs://nameservice) and restart it
Reconfigure the diff tool to use WebHDFS directly against the NameNode
Audit httpfs-site.xml and the HttpFS process environment for a stale or missing fs.defaultFS
Feature-detect at startup: if GETSNAPSHOTDIFFLISTING returns this error, disable paged diff UI instead of retrying

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; paged snapshot diff listing then works -->

Defensive patterns

Strategy: try-catch

Type guard

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

Try / catch

try {
  SnapshotDiffReportListing l = fs.getSnapshotDiffReportListing(path, oldSnap, newSnap, startPath, 0);
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("not supported for HttpFs")) {
    throw new UnsupportedFeatureException("paged snapshot diff needs HDFS-backed HttpFS", e);
  }
  throw e;
}

Prevention

Point paged-diff clients at WebHDFS on the NameNode
Health-check gateways with a DFS-only op before enabling diff pagination in UIs
Track which HttpFS endpoints are HDFS-backed in service metadata, not folklore

When it happens

Trigger: Client sends op=GETSNAPSHOTDIFFLISTING with snapshotdiffstartpath/snapshotdiffindex pagination params through HttpFS whose backing filesystem is not DistributedFileSystem.

Common situations: Incremental-diff tooling (e.g., HDFS replication/distcp difference viewers) configured with an HttpFS URL on a gateway backed by local or object storage; server config drift after migration off HDFS.

Related errors

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