cat_ranges doesn't pass kwargs to cat_file which generates block size mismatches which result in no cache usage

[bnlawrence]

I'm trying to use fsspec with non-default block-sizes for a local disk cache and access to remote s3/https resources. It seems that when cat_ranges is not used, all works as expected, but when usingcat_ranges, the cache is bypassed, as cat_ranges always goes out to the network.

If I've understood the problem correctly, AbstractFileSystem.cat_ranges accepts **kwargs but does not forward them when calling cat_file:

fsspec/spec.py:

 out.append(self.cat_file(p, s, e))   # <-- kwargs silently dropped

The consequence is that when CachingFileSystem._open uses block_size to look up blocks in its
on-disk cache and block_size is missing the call falls back to the default value, which (in my case) does not match the block size used to populate the cache, so every cat_ranges call fetches from the underlying (remote) filesystem instead of reading locally.

Solution

Locally patching AbstractFileSystem.cat_ranges to call self.cat_file(p, s, e, **kwargs) restores the expected cache reuse in our real integration case. I'm not brave enough to deliver a pull request with all your testing environment, but I hope that'd be trivial for you to check.

Environment

• Python: 3.12.13 (conda-forge, macOS arm64)
• fsspec: 2026.3.0
• s3fs: 2026.3.0

MWE

I've struggled to demonstrate this in a useful MWE, but in the spirit of trying to provide something, I got my LLM to generate the following which at least demonstrates what is obvious from the line of code above, that the kwargs are dropped ...

from __future__ import annotations
from fsspec.spec import AbstractFileSystem

class _SpyFS(AbstractFileSystem):
    """Minimal AbstractFileSystem that records kwargs received by cat_file."""

    protocol = "spy"

    def __init__(self):
        # Skip AbstractFileSystem.__init__ to avoid registration side-effects.
        self._kwargs_received: dict | None = None

    def cat_file(self, path, start=None, end=None, **kwargs):
        self._kwargs_received = kwargs
        return b"data"

def main() -> None:
    fs = _SpyFS()

    # Call cat_ranges with an explicit block_size kwarg.
    block_size = 2 * 1024 * 1024
    fs.cat_ranges(["dummy"], [0], [10], block_size=block_size)

    received = fs._kwargs_received
    print(f"kwargs passed to cat_file: {received}")

if __name__ == "__main__":
    main()

[bnlawrence]

Related to this, there's an additional issue which amplifies the problem. If one does this:

CachingFileSystem(s3fs.S3FileSystem(...), cache={...})
handle = fs.open('path', 'rb')

CachingFileSystem patches handle.cache for normal I/O paths but leaves handle.fs pointing at the raw backend filesystem. This means any code using handle.fs directly (including handle.fs.cat_ranges() completely bypasses the cache, but we'd expect it to use the cache (handle.read() and handle.seek() + handle.read() do, unlike handle.fs.cat_ranges()).

This affects libraries that call handle.fs.cat_ranges() for bulk remote reads—they incur full remote I/O on every operation, even with an active cache.

Potential solutions:

• Have CachingFileSystem wrap handle.fs as well (similar to wrapping handle.cache),
• Document this limitation clearly so users know to avoid it,
• Provide a cache-aware cat_ranges method on the handle itself

Currently, we work around this by inserting a per-handle FS adapter that intercepts cat_ranges and routes it through the cache, but this feels very hacky.

[martindurant]

I'd be happy to see kwargs passed through as you suggest for part 1 of this issue.

[martindurant]

This affects libraries that call handle.fs.cat_ranges() for bulk remote reads—they incur full remote I/O on every operation, even with an active cache.

Is this usage that you have seen? If yes, then your first solution sounds like the right one.