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.

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

• Cannot clean commit: File has trailing junk data.
• Committing file failed, could not rename
• Committing file failed. Target file already exists
• Directory does not exist or an I/O error occurred
• Directory is not empty

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

Appendix: 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)