{"record":{"id":"ff57aa3d1af30a80","repo":"apache/flink","slug":"file-is-not-an-instance-of-distributedfilestatus","errorCode":null,"errorMessage":"file is not an instance of DistributedFileStatus","messagePattern":"file is not an instance of DistributedFileStatus","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"flink-filesystems/flink-hadoop-fs/src/main/java/org/apache/flink/runtime/fs/hdfs/HadoopFileSystem.java","lineNumber":96,"sourceCode":"        return new Path(this.fs.getHomeDirectory().toUri());\n    }\n\n    @Override\n    public URI getUri() {\n        return fs.getUri();\n    }\n\n    @Override\n    public FileStatus getFileStatus(final Path f) throws IOException {\n        org.apache.hadoop.fs.FileStatus status = this.fs.getFileStatus(toHadoopPath(f));\n        return HadoopFileStatus.fromHadoopStatus(status);\n    }\n\n    @Override\n    public BlockLocation[] getFileBlockLocations(\n            final FileStatus file, final long start, final long len) throws IOException {\n        if (!(file instanceof HadoopFileStatus)) {\n            throw new IOException(\"file is not an instance of DistributedFileStatus\");\n        }\n\n        // shortcut - if the status already has the information, return it.\n        if (file instanceof LocatedHadoopFileStatus) {\n            return ((LocatedHadoopFileStatus) file).getBlockLocations();\n        }\n\n        final org.apache.hadoop.fs.FileStatus hadoopStatus =\n                ((HadoopFileStatus) file).getInternalFileStatus();\n\n        // second shortcut - if the internal status already has the information, return it.\n        // only if that is not the case, to the actual HDFS call (RPC to Name Node)\n        final org.apache.hadoop.fs.BlockLocation[] blkLocations =\n                hadoopStatus instanceof org.apache.hadoop.fs.LocatedFileStatus\n                        ? ((org.apache.hadoop.fs.LocatedFileStatus) hadoopStatus)\n                                .getBlockLocations()\n                        : fs.getFileBlockLocations(hadoopStatus, start, len);\n","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-filesystems/flink-hadoop-fs/src/main/java/org/apache/flink/runtime/fs/hdfs/HadoopFileSystem.java#L78-L114","documentation":"HadoopFileSystem.getFileBlockLocations requires the passed FileStatus to be a HadoopFileStatus (or its subclass LocatedHadoopFileStatus), because it must reach through to the wrapped org.apache.hadoop.fs.FileStatus to fetch block info. Passing any other FileStatus implementation is rejected with this IOException.","triggerScenarios":"Calling getFileBlockLocations(fileStatus, start, len) with a FileStatus obtained from a different FileSystem implementation (e.g. local or another plugin), a hand-constructed FileStatus, or a copied/deserialized status object.","commonSituations":"Code that mixes filesystems: stat a path on one filesystem, then ask another filesystem for block locations; generic utility code that accepts FileSystem + FileStatus from different sources; caching FileStatus objects across filesystem instances.","solutions":["Obtain the FileStatus from the SAME HadoopFileSystem instance: use hadoopFs.getFileStatus(path) and pass that result to getFileBlockLocations","Prefer the path-based overload getFileBlockLocations(path, start, len) which avoids the type coupling entirely"],"exampleFix":"// before\nFileStatus st = otherFs.getFileStatus(path);\nhadoopFs.getFileBlockLocations(st, 0, len); // throws\n// after\nFileStatus st = hadoopFs.getFileStatus(path);\nhadoopFs.getFileBlockLocations(st, 0, len);","handlingStrategy":"type-guard","validationCode":"// ensure status came from this filesystem before querying locations\nFileStatus status = fs.getFileStatus(path); // same fs instance\nBlockLocation[] locs = fs.getFileBlockLocations(status, 0, status.getLen());","typeGuard":"boolean isHadoopStatus(FileStatus s) {\n    return s instanceof org.apache.flink.runtime.fs.hdfs.HadoopFileSystem.HadoopFileStatus;\n}","tryCatchPattern":"try {\n    locs = fs.getFileBlockLocations(status, 0, len);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"not an instance of\")) {\n        // re-fetch status from this fs, or use the path-based overload\n    }\n}","preventionTips":["Always stat and query locations through the same FileSystem instance","Prefer the Path-based getFileBlockLocations overload","Never persist and reuse FileStatus objects across filesystems"],"tags":["hdfs","type-mismatch","block-location","api-misuse"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}