{"record":{"id":"b18e80ccf7a9e578","repo":"apache/hadoop","slug":"unable-to-support-fsfileblocklocationslegacy-becau","errorCode":null,"errorMessage":"Unable to support FSFileBlockLocationsLegacy because the file system is not DistributedFileSystem.","messagePattern":"Unable to support FSFileBlockLocationsLegacy because the file system is not DistributedFileSystem\\.","errorType":"exception","errorClass":"IOException","httpStatus":500,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/fs/http/server/FSOperations.java","lineNumber":2284,"sourceCode":"     * @param path the path to retrieve the location\n     * @param offsetValue offset into the given file\n     * @param lengthValue length for which to get locations for\n     */\n    public FSFileBlockLocationsLegacy(String path, long offsetValue, long lengthValue) {\n      this.path = new Path(path);\n      this.offsetValue = offsetValue;\n      this.lengthValue = lengthValue;\n    }\n\n    @Override\n    public Map execute(FileSystem fs) throws IOException {\n      if (fs instanceof DistributedFileSystem) {\n        DistributedFileSystem dfs = (DistributedFileSystem)fs;\n        LocatedBlocks locations = dfs.getLocatedBlocks(\n            this.path, this.offsetValue, this.lengthValue);\n        return JsonUtil.toJsonMap(locations);\n      }\n      throw new IOException(\"Unable to support FSFileBlockLocationsLegacy \" +\n          \"because the file system is not DistributedFileSystem.\");\n    }\n  }\n\n  /**\n   * Executor that performs a linkFile-status FileSystemAccess files\n   * system operation.\n   */\n  @InterfaceAudience.Private\n  @SuppressWarnings(\"rawtypes\")\n  public static class FSFileLinkStatus\n      implements FileSystemAccess.FileSystemExecutor<Map> {\n    final private Path path;\n\n    /**\n     * Creates a linkFile-status executor.\n     *\n     * @param path the path to retrieve the status.","sourceCodeStart":2266,"sourceCodeEnd":2302,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/fs/http/server/FSOperations.java#L2266-L2302","documentation":"FSOperations.FSFileBlockLocationsLegacy.execute() serves the legacy block-locations request by calling DistributedFileSystem.getLocatedBlocks() and JSON-serializing LocatedBlocks; the legacy wire shape cannot be produced from the generic FileSystem API. When the backing filesystem is not DistributedFileSystem it throws plain IOException (not UnsupportedOperationException), which HttpExceptionUtils maps to HTTP 500 rather than 400.","triggerScenarios":"An older WebHDFS client requests op=GETFILEBLOCKLOCATIONS through an HttpFS server whose fs.defaultFS is file:/// or an object store, hitting the legacy executor instead of the modern block-locations path.","commonSituations":"Legacy MapReduce/scheduling tools computing input splits via HttpFS; mixed clusters where some gateways are HDFS-backed and others are not; upgrades that left old client jars asking for the legacy format.","solutions":["Configure the HttpFS server's fs.defaultFS to the HDFS nameservice and restart it","Upgrade the client to a Hadoop version that uses the non-legacy block-locations call, which has broader filesystem support","Compute splits against WebHDFS on the NameNode directly for HDFS data","Distinguish this 500-capability error from real server faults by the message text before debugging deeper"],"exampleFix":"<!-- before: httpfs-site.xml -->\n<property><name>fs.defaultFS</name><value>file:///</value></property>\n<!-- after -->\n<property><name>fs.defaultFS</name><value>hdfs://ns1</value></property>\n<!-- restart HttpFS; legacy GETFILEBLOCKLOCATIONS then returns LocatedBlocks JSON -->","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"static DistributedFileSystem asDfs(FileSystem fs) {\n  return fs instanceof DistributedFileSystem ? (DistributedFileSystem) fs : null;\n}","tryCatchPattern":"try {\n  BlockLocation[] locs = fs.getFileBlockLocations(path, 0, len); // legacy path via HttpFS\n} catch (IOException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"not DistributedFileSystem\")) {\n    // legacy executor unavailable: compute splits against WebHDFS on the NameNode\n    throw new UnsupportedFeatureException(\"legacy block locations need HDFS-backed HttpFS\", e);\n  }\n  throw e;\n}","preventionTips":["Note this variant arrives as HTTP 500 (plain IOException), unlike the 400 UnsupportedOperationException siblings","Upgrade legacy split-computing clients to modern Hadoop versions","Point split computation at the HDFS cluster, not at non-HDFS gateways"],"tags":["httpfs","webhdfs","block-locations","legacy-client","unsupported-operation","fs-defaultfs"],"backgroundTag":"unsupported-filesystem-operation","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}