{"record":{"id":"c411c75a393d8dc3","repo":"apache/hadoop","slug":"getfilechecksum-path-long-is-not-supported-by","errorCode":null,"errorMessage":"getFileChecksum(Path, long) is not supported by ","messagePattern":"getFileChecksum\\(Path, long\\) is not supported by ","errorType":"exception","errorClass":"UnsupportedFileSystemException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DistributedFileSystem.java","lineNumber":2085,"sourceCode":"  @Override\n  public FileChecksum getFileChecksum(Path f, final long length)\n      throws IOException {\n    statistics.incrementReadOps(1);\n    storageStatistics.incrementOpCounter(OpType.GET_FILE_CHECKSUM);\n    Path absF = fixRelativePart(f);\n    return new FileSystemLinkResolver<FileChecksum>() {\n      @Override\n      public FileChecksum doCall(final Path p) throws IOException {\n        return dfs.getFileChecksumWithCombineMode(getPathName(p), length);\n      }\n\n      @Override\n      public FileChecksum next(final FileSystem fs, final Path p)\n          throws IOException {\n        if (fs instanceof DistributedFileSystem) {\n          return fs.getFileChecksum(p, length);\n        } else {\n          throw new UnsupportedFileSystemException(\n              \"getFileChecksum(Path, long) is not supported by \"\n                  + fs.getClass().getSimpleName());\n        }\n      }\n    }.resolve(this, absF);\n  }\n\n  @Override\n  public void setPermission(Path p, final FsPermission permission\n  ) throws IOException {\n    statistics.incrementWriteOps(1);\n    storageStatistics.incrementOpCounter(OpType.SET_PERMISSION);\n    Path absF = fixRelativePart(p);\n    new FileSystemLinkResolver<Void>() {\n      @Override\n      public Void doCall(final Path p) throws IOException {\n        dfs.setPermission(getPathName(p), permission);\n        return null;","sourceCodeStart":2067,"sourceCodeEnd":2103,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DistributedFileSystem.java#L2067-L2103","documentation":"getFileChecksum(Path, long) with a length argument uses HDFS-specific combined-mode checksums (dfs.getFileChecksumWithCombineMode). When a symlink resolves onto a filesystem that is not a DistributedFileSystem, the generic FileSystem contract cannot express this operation, so the resolver throws UnsupportedFileSystemException naming the target filesystem class.","triggerScenarios":"Calling fs.getFileChecksum(p, length) where p is an HDFS symlink whose target resolves onto a non-HDFS filesystem (file://, s3a://, etc.), so next(fs, p) receives a foreign FileSystem instance.","commonSituations":"Data-integrity tools computing partial checksums over hybrid lakes with cross-scheme symlinks; checksum verification code that worked on plain HDFS paths after symlinks were introduced by a re-layout; mount-table (viewfs) setups routing some paths to object stores.","solutions":["Resolve the link target yourself and only call getFileChecksum(p, length) on the DistributedFileSystem that owns the target.","Use the single-argument getFileChecksum(p), which is part of the generic FileSystem API and works cross-filesystem via fallback.","Restructure so checksum verification never traverses cross-filesystem symlinks.","Skip/flag foreign-scheme paths in verification jobs instead of failing the whole run."],"exampleFix":"// before\nFileChecksum cs = hdfs.getFileChecksum(linkPath, length); // UnsupportedFileSystemException\n\n// after\nPath target = hdfs.getLinkTarget(linkPath);\nFileSystem targetFs = FileSystem.get(target.toUri(), conf);\nFileChecksum cs = targetFs instanceof DistributedFileSystem\n    ? targetFs.getFileChecksum(target, length)\n    : targetFs.getFileChecksum(target);","handlingStrategy":"fallback","validationCode":"Path target = fs.getLinkTarget(p);\nFileSystem tfs = FileSystem.get(target.toUri(), conf);\nif (!(tfs instanceof DistributedFileSystem)) {\n  // plan to use single-arg getFileChecksum on tfs instead\n}","typeGuard":null,"tryCatchPattern":"try {\n  cs = fs.getFileChecksum(p, length);\n} catch (UnsupportedFileSystemException e) {\n  cs = fs.getFileChecksum(p); // generic API works cross-filesystem\n}","preventionTips":["Reserve getFileChecksum(p, length) for paths known to live on HDFS.","Verify resolved scheme/authority before HDFS-specific checksum APIs.","For integrity tools over hybrid lakes, branch per scheme rather than assuming DFS semantics."],"tags":["hdfs","checksum","symlink","cross-filesystem","unsupported-filesystem","distributed-filesystem"],"backgroundTag":"symlink-cross-filesystem-unsupported","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}