apache/flink · error · IOException

File status does not belong to the LocalFileSystem: {}

Error message

File status does not belong to the LocalFileSystem: {}

What it means

Thrown by LocalFileSystem.getFileBlockLocations() when the supplied FileStatus is not an instance of LocalFileStatus. LocalFileSystem can only return block locations for files it created/owns, because local files have no real block layout.

Source

Thrown at flink-core/src/main/java/org/apache/flink/core/fs/local/LocalFileSystem.java:91

     * cache the proper path here.
     */
    private final URI homeDir;

    /** Constructs a new <code>LocalFileSystem</code> object. */
    public LocalFileSystem() {
        this.workingDir = new File(System.getProperty("user.dir")).toURI();
        this.homeDir = new File(System.getProperty("user.home")).toURI();
    }

    // ------------------------------------------------------------------------

    @Override
    public BlockLocation[] getFileBlockLocations(FileStatus file, long start, long len)
            throws IOException {
        if (file instanceof LocalFileStatus) {
            return ((LocalFileStatus) file).getBlockLocations();
        }
        throw new IOException("File status does not belong to the LocalFileSystem: " + file);
    }

    @Override
    public FileStatus getFileStatus(Path f) throws IOException {
        final File path = pathToFile(f);
        if (path.exists()) {
            return new LocalFileStatus(path, this);
        } else {
            throw new FileNotFoundException(
                    "File "
                            + f
                            + " does not exist or the user running "
                            + "Flink ('"
                            + System.getProperty("user.name")
                            + "') has insufficient permissions to access it.");
        }
    }

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Call getFileBlockLocations on the same FileSystem instance that produced the FileStatus.
2. Ensure the FileStatus comes from LocalFileSystem.getFileStatus() or LocalFileSystem.listStatus().
3. Guard: `if (status instanceof LocalFileStatus)` before calling.

Example fix

// before
FileStatus s = hdfs.getFileStatus(p);
BlockLocation[] bl = localFs.getFileBlockLocations(s, 0, len);

// after
FileStatus s = localFs.getFileStatus(p);
BlockLocation[] bl = localFs.getFileBlockLocations(s, 0, len);

static boolean belongsToLocalFs(FileStatus s) {
    return s instanceof LocalFileStatus;
}

try {
    fs.getFileBlockLocations(status, 0, len);
} catch (IOException e) {
    if (e.getMessage().startsWith("File status does not belong to the LocalFileSystem")) {
        // re-fetch status from this FS and retry
    }
}

When it happens

Trigger: Passing a FileStatus obtained from a different filesystem (e.g. HDFS, S3) into LocalFileSystem.getFileBlockLocations(file, start, len).

Common situations: Code that generically iterates FileStatuses from one FS and passes them to another FS's getFileBlockLocations; mocking FileStatus in tests with a non-LocalFileStatus subclass; mixing filesystem instances in input format setup.

Related errors

• File {} does not exist or the user running Flink ('{}') has
• Directory {} does not exist or an I/O error occurred
• Directory {} is not empty
• {}
• File already exists: {}

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/69edcf27dc013638. Report an issue: GitHub.