Unable to access kerchunk file on s3

[chiaweh2]

Zarr version

v2.18.3 and V3.1.1

Numcodecs version

0.15.1

Python Version

3.11

Operating System

Linux

Installation

using conda

Description

What happened?

when using fsspec.filesystem with xr.open_dataset there seems to have inconsistent results at different conda environments. The code snippets to generate the error is below

import xarray as xr
import fsspec

fs = fsspec.filesystem(
    "reference", 
    fo='s3://noaa-oar-cefi-regional-mom6-pds/northwest_atlantic/full_domain/hindcast/monthly/regrid/r20230520/ssh.nwa.full.hcast.monthly.regrid.r20230520.199301-201912.json',
    remote_protocol="s3", 
    remote_options={"anon":True}
)
 
ds = xr.open_dataset(fs.get_mapper(""), engine='zarr',backend_kwargs={"consolidated": False})

The error message is

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[44], line 12
      3 import zarr
      5 fs = fsspec.filesystem(
      6     "reference", 
      7     fo='s3://noaa-oar-cefi-regional-mom6-pds/northwest_atlantic/full_domain/hindcast/monthly/regrid/r20230520/ssh.nwa.full.hcast.monthly.regrid.r20230520.199301-201912.json',
      8     remote_protocol="s3", 
      9     remote_options={"anon":True}
     10 )
---> 12 ds = xr.open_dataset(fs.get_mapper(""), engine='zarr',backend_kwargs={"consolidated": False})

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/xarray/backends/api.py:571, in open_dataset(filename_or_obj, engine, chunks, cache, decode_cf, mask_and_scale, decode_times, decode_timedelta, use_cftime, concat_characters, decode_coords, drop_variables, inline_array, chunked_array_type, from_array_kwargs, backend_kwargs, **kwargs)
    559 decoders = _resolve_decoders_kwargs(
    560     decode_cf,
    561     open_backend_dataset_parameters=backend.open_dataset_parameters,
   (...)
    567     decode_coords=decode_coords,
    568 )
    570 overwrite_encoded_chunks = kwargs.pop("overwrite_encoded_chunks", None)
--> 571 backend_ds = backend.open_dataset(
    572     filename_or_obj,
    573     drop_variables=drop_variables,
    574     **decoders,
    575     **kwargs,
    576 )
    577 ds = _dataset_from_backend_dataset(
    578     backend_ds,
    579     filename_or_obj,
   (...)
    589     **kwargs,
    590 )
    591 return ds

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/xarray/backends/zarr.py:1170, in ZarrBackendEntrypoint.open_dataset(self, filename_or_obj, mask_and_scale, decode_times, concat_characters, decode_coords, drop_variables, use_cftime, decode_timedelta, group, mode, synchronizer, consolidated, chunk_store, storage_options, stacklevel, zarr_version)
   1149 def open_dataset(  # type: ignore[override]  # allow LSP violation, not supporting **kwargs
   1150     self,
   1151     filename_or_obj: str | os.PathLike[Any] | BufferedIOBase | AbstractDataStore,
   (...)
   1167     zarr_version=None,
   1168 ) -> Dataset:
   1169     filename_or_obj = _normalize_path(filename_or_obj)
-> 1170     store = ZarrStore.open_group(
   1171         filename_or_obj,
   1172         group=group,
   1173         mode=mode,
   1174         synchronizer=synchronizer,
   1175         consolidated=consolidated,
   1176         consolidate_on_close=False,
   1177         chunk_store=chunk_store,
   1178         storage_options=storage_options,
   1179         stacklevel=stacklevel + 1,
   1180         zarr_version=zarr_version,
   1181     )
   1183     store_entrypoint = StoreBackendEntrypoint()
   1184     with close_on_error(store):

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/xarray/backends/zarr.py:500, in ZarrStore.open_group(cls, store, mode, synchronizer, group, consolidated, consolidate_on_close, chunk_store, storage_options, append_dim, write_region, safe_chunks, stacklevel, zarr_version, write_empty)
    498     zarr_group = zarr.open_consolidated(store, **open_kwargs)
    499 else:
--> 500     zarr_group = zarr.open_group(store, **open_kwargs)
    501 close_store_on_close = zarr_group.store is not store
    502 return cls(
    503     zarr_group,
    504     mode,
   (...)
    510     close_store_on_close,
    511 )

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/api/synchronous.py:531, in open_group(store, mode, cache_attrs, synchronizer, path, chunk_store, storage_options, zarr_version, zarr_format, meta_array, attributes, use_consolidated)
    454 def open_group(
    455     store: StoreLike | None = None,
    456     *,
   (...)
    467     use_consolidated: bool | str | None = None,
    468 ) -> Group:
    469     """Open a group using file-mode-like semantics.
    470 
    471     Parameters
   (...)
    528         The new group.
    529     """
    530     return Group(
--> 531         sync(
    532             async_api.open_group(
    533                 store=store,
    534                 mode=mode,
    535                 cache_attrs=cache_attrs,
    536                 synchronizer=synchronizer,
    537                 path=path,
    538                 chunk_store=chunk_store,
    539                 storage_options=storage_options,
    540                 zarr_version=zarr_version,
    541                 zarr_format=zarr_format,
    542                 meta_array=meta_array,
    543                 attributes=attributes,
    544                 use_consolidated=use_consolidated,
    545             )
    546         )
    547     )

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/core/sync.py:163, in sync(coro, loop, timeout)
    160 return_result = next(iter(finished)).result()
    162 if isinstance(return_result, BaseException):
--> 163     raise return_result
    164 else:
    165     return return_result

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/core/sync.py:119, in _runner(coro)
    114 """
    115 Await a coroutine and return the result of running it. If awaiting the coroutine raises an
    116 exception, the exception will be returned.
    117 """
    118 try:
--> 119     return await coro
    120 except Exception as ex:
    121     return ex

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/api/asynchronous.py:838, in open_group(store, mode, cache_attrs, synchronizer, path, chunk_store, storage_options, zarr_version, zarr_format, meta_array, attributes, use_consolidated)
    835 if chunk_store is not None:
    836     warnings.warn("chunk_store is not yet implemented", RuntimeWarning, stacklevel=2)
--> 838 store_path = await make_store_path(store, mode=mode, storage_options=storage_options, path=path)
    839 if attributes is None:
    840     attributes = {}

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/storage/_common.py:363, in make_store_path(store_like, path, mode, storage_options)
    359     if storage_options:
    360         raise ValueError(
    361             "'storage_options was provided but is not used for FSMap store_like objects. Specify the storage options when creating the FSMap instance instead."
    362         )
--> 363     store = FsspecStore.from_mapper(store_like, read_only=_read_only)
    364 else:
    365     raise TypeError(f"Unsupported type for store_like: '{type(store_like).__name__}'")

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/storage/_fsspec.py:202, in FsspecStore.from_mapper(cls, fs_map, read_only, allowed_exceptions)
    178 @classmethod
    179 def from_mapper(
    180     cls,
   (...)
    183     allowed_exceptions: tuple[type[Exception], ...] = ALLOWED_EXCEPTIONS,
    184 ) -> FsspecStore:
    185     """
    186     Create a FsspecStore from a FSMap object.
    187 
   (...)
    200     FsspecStore
    201     """
--> 202     fs = _make_async(fs_map.fs)
    203     return cls(
    204         fs=fs,
    205         path=fs_map.root,
    206         read_only=read_only,
    207         allowed_exceptions=allowed_exceptions,
    208     )

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/storage/_fsspec.py:57, in _make_async(fs)
     55     fs_dict = json.loads(fs.to_json())
     56     fs_dict["asynchronous"] = True
---> 57     return fsspec.AbstractFileSystem.from_json(json.dumps(fs_dict))
     59 if fsspec_version < parse_version("2024.12.0"):
     60     raise ImportError(
     61         f"The filesystem '{fs}' is synchronous, and the required "
     62         "AsyncFileSystemWrapper is not available. Upgrade fsspec to version "
     63         "2024.12.0 or later to enable this functionality."
     64     )

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/fsspec/spec.py:1480, in AbstractFileSystem.from_json(blob)
   1459 """
   1460 Recreate a filesystem instance from JSON representation.
   1461 
   (...)
   1476 at import time.
   1477 """
   1478 from .json import FilesystemJSONDecoder
-> 1480 return json.loads(blob, cls=FilesystemJSONDecoder)

File ~/.conda/envs/regional-mom6/lib/python3.11/json/__init__.py:359, in loads(s, cls, object_hook, parse_float, parse_int, parse_constant, object_pairs_hook, **kw)
    357 if parse_constant is not None:
    358     kw['parse_constant'] = parse_constant
--> 359 return cls(**kw).decode(s)

File ~/.conda/envs/regional-mom6/lib/python3.11/json/decoder.py:337, in JSONDecoder.decode(self, s, _w)
    332 def decode(self, s, _w=WHITESPACE.match):
    333     """Return the Python representation of ``s`` (a ``str`` instance
    334     containing a JSON document).
    335 
    336     """
--> 337     obj, end = self.raw_decode(s, idx=_w(s, 0).end())
    338     end = _w(s, end).end()
    339     if end != len(s):

File ~/.conda/envs/regional-mom6/lib/python3.11/json/decoder.py:353, in JSONDecoder.raw_decode(self, s, idx)
    344 """Decode a JSON document from ``s`` (a ``str`` beginning with
    345 a JSON document) and return a 2-tuple of the Python
    346 representation and the index in ``s`` where the document ended.
   (...)
    350 
    351 """
    352 try:
--> 353     obj, end = self.scan_once(s, idx)
    354 except StopIteration as err:
    355     raise JSONDecodeError("Expecting value", s, err.value) from None

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/fsspec/json.py:97, in FilesystemJSONDecoder.custom_object_hook(self, dct)
     95 if "cls" in dct:
     96     if (obj_cls := self.try_resolve_fs_cls(dct)) is not None:
---> 97         return AbstractFileSystem.from_dict(dct)
     98     if (obj_cls := self.try_resolve_path_cls(dct)) is not None:
     99         return obj_cls(dct["str"])

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/fsspec/spec.py:1556, in AbstractFileSystem.from_dict(dct)
   1553 dct.pop("cls", None)
   1554 dct.pop("protocol", None)
-> 1556 return cls(
   1557     *json_decoder.unmake_serializable(dct.pop("args", ())),
   1558     **json_decoder.unmake_serializable(dct),
   1559 )

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/fsspec/spec.py:81, in _Cached.__call__(cls, *args, **kwargs)
     79     return cls._cache[token]
     80 else:
---> 81     obj = super().__call__(*args, **kwargs)
     82     # Setting _fs_token here causes some static linters to complain.
     83     obj._fs_token_ = token

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/fsspec/implementations/reference.py:770, in ReferenceFileSystem.__init__(self, fo, target, ref_storage_args, target_protocol, target_options, remote_protocol, remote_options, fs, template_overrides, simple_templates, max_gap, max_block, cache_size, **kwargs)
    768     self.fss[k] = AsyncFileSystemWrapper(f, asynchronous=self.asynchronous)
    769 elif self.asynchronous ^ f.asynchronous:
--> 770     raise ValueError(
    771         "Reference-FS's target filesystem must have same value "
    772         "of asynchronous"
    773     )

ValueError: Reference-FS's target filesystem must have same value of asynchronous

the version will not work are

xarry version: 2025.6.1
fsspec version: 2025.7.0
zarr version: 3.1.1
s3fs version: 2025.7.0

where the version work are

xarry version: 2024.3.0
fsspec version: 2025.2.0
zarr version: 2.18.3
s3fs version: 2025.2.0

What did you expect to happen?

no error

Minimal Complete Verifiable Example

import xarray as xr
import fsspec

fs = fsspec.filesystem(
    "reference", 
    fo='s3://noaa-oar-cefi-regional-mom6-pds/northwest_atlantic/full_domain/hindcast/monthly/regrid/r20230520/ssh.nwa.full.hcast.monthly.regrid.r20230520.199301-201912.json',
    remote_protocol="s3", 
    remote_options={"anon":True}
)
 
ds = xr.open_dataset(fs.get_mapper(""), engine='zarr',backend_kwargs={"consolidated": False})

MVCE confirmation

• Minimal example — the example is as focused as reasonably possible to demonstrate the underlying issue in xarray.
• Complete example — the example is self-contained, including all data and the text of any traceback.
• Verifiable example — the example copy & pastes into an IPython prompt or Binder notebook, returning the result.
• New issue — a search of GitHub Issues suggests this is not a duplicate.
• Recent environment — the issue occurs with the latest version of xarray and its dependencies.

Relevant log output

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[44], line 12
      3 import zarr
      5 fs = fsspec.filesystem(
      6     "reference", 
      7     fo='s3://noaa-oar-cefi-regional-mom6-pds/northwest_atlantic/full_domain/hindcast/monthly/regrid/r20230520/ssh.nwa.full.hcast.monthly.regrid.r20230520.199301-201912.json',
      8     remote_protocol="s3", 
      9     remote_options={"anon":True}
     10 )
---> 12 ds = xr.open_dataset(fs.get_mapper(""), engine='zarr',backend_kwargs={"consolidated": False})

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/xarray/backends/api.py:571, in open_dataset(filename_or_obj, engine, chunks, cache, decode_cf, mask_and_scale, decode_times, decode_timedelta, use_cftime, concat_characters, decode_coords, drop_variables, inline_array, chunked_array_type, from_array_kwargs, backend_kwargs, **kwargs)
    559 decoders = _resolve_decoders_kwargs(
    560     decode_cf,
    561     open_backend_dataset_parameters=backend.open_dataset_parameters,
   (...)
    567     decode_coords=decode_coords,
    568 )
    570 overwrite_encoded_chunks = kwargs.pop("overwrite_encoded_chunks", None)
--> 571 backend_ds = backend.open_dataset(
    572     filename_or_obj,
    573     drop_variables=drop_variables,
    574     **decoders,
    575     **kwargs,
    576 )
    577 ds = _dataset_from_backend_dataset(
    578     backend_ds,
    579     filename_or_obj,
   (...)
    589     **kwargs,
    590 )
    591 return ds

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/xarray/backends/zarr.py:1170, in ZarrBackendEntrypoint.open_dataset(self, filename_or_obj, mask_and_scale, decode_times, concat_characters, decode_coords, drop_variables, use_cftime, decode_timedelta, group, mode, synchronizer, consolidated, chunk_store, storage_options, stacklevel, zarr_version)
   1149 def open_dataset(  # type: ignore[override]  # allow LSP violation, not supporting **kwargs
   1150     self,
   1151     filename_or_obj: str | os.PathLike[Any] | BufferedIOBase | AbstractDataStore,
   (...)
   1167     zarr_version=None,
   1168 ) -> Dataset:
   1169     filename_or_obj = _normalize_path(filename_or_obj)
-> 1170     store = ZarrStore.open_group(
   1171         filename_or_obj,
   1172         group=group,
   1173         mode=mode,
   1174         synchronizer=synchronizer,
   1175         consolidated=consolidated,
   1176         consolidate_on_close=False,
   1177         chunk_store=chunk_store,
   1178         storage_options=storage_options,
   1179         stacklevel=stacklevel + 1,
   1180         zarr_version=zarr_version,
   1181     )
   1183     store_entrypoint = StoreBackendEntrypoint()
   1184     with close_on_error(store):

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/xarray/backends/zarr.py:500, in ZarrStore.open_group(cls, store, mode, synchronizer, group, consolidated, consolidate_on_close, chunk_store, storage_options, append_dim, write_region, safe_chunks, stacklevel, zarr_version, write_empty)
    498     zarr_group = zarr.open_consolidated(store, **open_kwargs)
    499 else:
--> 500     zarr_group = zarr.open_group(store, **open_kwargs)
    501 close_store_on_close = zarr_group.store is not store
    502 return cls(
    503     zarr_group,
    504     mode,
   (...)
    510     close_store_on_close,
    511 )

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/api/synchronous.py:531, in open_group(store, mode, cache_attrs, synchronizer, path, chunk_store, storage_options, zarr_version, zarr_format, meta_array, attributes, use_consolidated)
    454 def open_group(
    455     store: StoreLike | None = None,
    456     *,
   (...)
    467     use_consolidated: bool | str | None = None,
    468 ) -> Group:
    469     """Open a group using file-mode-like semantics.
    470 
    471     Parameters
   (...)
    528         The new group.
    529     """
    530     return Group(
--> 531         sync(
    532             async_api.open_group(
    533                 store=store,
    534                 mode=mode,
    535                 cache_attrs=cache_attrs,
    536                 synchronizer=synchronizer,
    537                 path=path,
    538                 chunk_store=chunk_store,
    539                 storage_options=storage_options,
    540                 zarr_version=zarr_version,
    541                 zarr_format=zarr_format,
    542                 meta_array=meta_array,
    543                 attributes=attributes,
    544                 use_consolidated=use_consolidated,
    545             )
    546         )
    547     )

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/core/sync.py:163, in sync(coro, loop, timeout)
    160 return_result = next(iter(finished)).result()
    162 if isinstance(return_result, BaseException):
--> 163     raise return_result
    164 else:
    165     return return_result

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/core/sync.py:119, in _runner(coro)
    114 """
    115 Await a coroutine and return the result of running it. If awaiting the coroutine raises an
    116 exception, the exception will be returned.
    117 """
    118 try:
--> 119     return await coro
    120 except Exception as ex:
    121     return ex

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/api/asynchronous.py:838, in open_group(store, mode, cache_attrs, synchronizer, path, chunk_store, storage_options, zarr_version, zarr_format, meta_array, attributes, use_consolidated)
    835 if chunk_store is not None:
    836     warnings.warn("chunk_store is not yet implemented", RuntimeWarning, stacklevel=2)
--> 838 store_path = await make_store_path(store, mode=mode, storage_options=storage_options, path=path)
    839 if attributes is None:
    840     attributes = {}

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/storage/_common.py:363, in make_store_path(store_like, path, mode, storage_options)
    359     if storage_options:
    360         raise ValueError(
    361             "'storage_options was provided but is not used for FSMap store_like objects. Specify the storage options when creating the FSMap instance instead."
    362         )
--> 363     store = FsspecStore.from_mapper(store_like, read_only=_read_only)
    364 else:
    365     raise TypeError(f"Unsupported type for store_like: '{type(store_like).__name__}'")

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/storage/_fsspec.py:202, in FsspecStore.from_mapper(cls, fs_map, read_only, allowed_exceptions)
    178 @classmethod
    179 def from_mapper(
    180     cls,
   (...)
    183     allowed_exceptions: tuple[type[Exception], ...] = ALLOWED_EXCEPTIONS,
    184 ) -> FsspecStore:
    185     """
    186     Create a FsspecStore from a FSMap object.
    187 
   (...)
    200     FsspecStore
    201     """
--> 202     fs = _make_async(fs_map.fs)
    203     return cls(
    204         fs=fs,
    205         path=fs_map.root,
    206         read_only=read_only,
    207         allowed_exceptions=allowed_exceptions,
    208     )

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/zarr/storage/_fsspec.py:57, in _make_async(fs)
     55     fs_dict = json.loads(fs.to_json())
     56     fs_dict["asynchronous"] = True
---> 57     return fsspec.AbstractFileSystem.from_json(json.dumps(fs_dict))
     59 if fsspec_version < parse_version("2024.12.0"):
     60     raise ImportError(
     61         f"The filesystem '{fs}' is synchronous, and the required "
     62         "AsyncFileSystemWrapper is not available. Upgrade fsspec to version "
     63         "2024.12.0 or later to enable this functionality."
     64     )

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/fsspec/spec.py:1480, in AbstractFileSystem.from_json(blob)
   1459 """
   1460 Recreate a filesystem instance from JSON representation.
   1461 
   (...)
   1476 at import time.
   1477 """
   1478 from .json import FilesystemJSONDecoder
-> 1480 return json.loads(blob, cls=FilesystemJSONDecoder)

File ~/.conda/envs/regional-mom6/lib/python3.11/json/__init__.py:359, in loads(s, cls, object_hook, parse_float, parse_int, parse_constant, object_pairs_hook, **kw)
    357 if parse_constant is not None:
    358     kw['parse_constant'] = parse_constant
--> 359 return cls(**kw).decode(s)

File ~/.conda/envs/regional-mom6/lib/python3.11/json/decoder.py:337, in JSONDecoder.decode(self, s, _w)
    332 def decode(self, s, _w=WHITESPACE.match):
    333     """Return the Python representation of ``s`` (a ``str`` instance
    334     containing a JSON document).
    335 
    336     """
--> 337     obj, end = self.raw_decode(s, idx=_w(s, 0).end())
    338     end = _w(s, end).end()
    339     if end != len(s):

File ~/.conda/envs/regional-mom6/lib/python3.11/json/decoder.py:353, in JSONDecoder.raw_decode(self, s, idx)
    344 """Decode a JSON document from ``s`` (a ``str`` beginning with
    345 a JSON document) and return a 2-tuple of the Python
    346 representation and the index in ``s`` where the document ended.
   (...)
    350 
    351 """
    352 try:
--> 353     obj, end = self.scan_once(s, idx)
    354 except StopIteration as err:
    355     raise JSONDecodeError("Expecting value", s, err.value) from None

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/fsspec/json.py:97, in FilesystemJSONDecoder.custom_object_hook(self, dct)
     95 if "cls" in dct:
     96     if (obj_cls := self.try_resolve_fs_cls(dct)) is not None:
---> 97         return AbstractFileSystem.from_dict(dct)
     98     if (obj_cls := self.try_resolve_path_cls(dct)) is not None:
     99         return obj_cls(dct["str"])

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/fsspec/spec.py:1556, in AbstractFileSystem.from_dict(dct)
   1553 dct.pop("cls", None)
   1554 dct.pop("protocol", None)
-> 1556 return cls(
   1557     *json_decoder.unmake_serializable(dct.pop("args", ())),
   1558     **json_decoder.unmake_serializable(dct),
   1559 )

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/fsspec/spec.py:81, in _Cached.__call__(cls, *args, **kwargs)
     79     return cls._cache[token]
     80 else:
---> 81     obj = super().__call__(*args, **kwargs)
     82     # Setting _fs_token here causes some static linters to complain.
     83     obj._fs_token_ = token

File ~/.conda/envs/regional-mom6/lib/python3.11/site-packages/fsspec/implementations/reference.py:770, in ReferenceFileSystem.__init__(self, fo, target, ref_storage_args, target_protocol, target_options, remote_protocol, remote_options, fs, template_overrides, simple_templates, max_gap, max_block, cache_size, **kwargs)
    768     self.fss[k] = AsyncFileSystemWrapper(f, asynchronous=self.asynchronous)
    769 elif self.asynchronous ^ f.asynchronous:
--> 770     raise ValueError(
    771         "Reference-FS's target filesystem must have same value "
    772         "of asynchronous"
    773     )

ValueError: Reference-FS's target filesystem must have same value of asynchronous

Anything else we need to know?

the version will not work are

xarry version: 2025.6.1
fsspec version: 2025.7.0
zarr version: 3.1.1
s3fs version: 2025.7.0

where the version work are

xarry version: 2024.3.0
fsspec version: 2025.2.0
zarr version: 2.18.3
s3fs version: 2025.2.0

Environment

Details

/home/chsu/.conda/envs/regional-mom6/lib/python3.11/site-packages/_distutils_hack/init.py:26: UserWarning: Setuptools is replacing distutils.
warnings.warn("Setuptools is replacing distutils.")

INSTALLED VERSIONS

commit: None
python: 3.11.9 | packaged by conda-forge | (main, Apr 19 2024, 18:36:13) [GCC 12.3.0]
python-bits: 64
OS: Linux
OS-release: 4.18.0-553.63.1.el8_10.x86_64
machine: x86_64
processor: x86_64
byteorder: little
LC_ALL: None
LANG: en_US.UTF-8
LOCALE: ('en_US', 'UTF-8')
libhdf5: 1.14.3
libnetcdf: 4.9.2

xarray: 2025.6.1
pandas: 2.2.2
numpy: 1.26.4
scipy: 1.13.1
netCDF4: 1.6.5
pydap: installed
h5netcdf: None
h5py: None
zarr: 3.1.1
cftime: 1.6.4
nc_time_axis: None
iris: None
bottleneck: None
dask: 2024.5.2
distributed: 2024.5.2
matplotlib: 3.8.4
cartopy: None
seaborn: None
numbagg: None
fsspec: 2025.7.0
cupy: None
pint: None
sparse: 0.15.4
flox: None
numpy_groupies: None
setuptools: 70.0.0
pip: 24.0
conda: None
pytest: 8.2.2
mypy: None
IPython: 8.25.0
sphinx: None

Steps to reproduce

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "zarr@git+https://github.com/zarr-developers/zarr-python.git@main",
#   "xarray",
#   "fsspec",
#   "s3fs"
# ]
# ///
#
# This script automatically imports the development branch of zarr to check for issues

import zarr
import xarray as xr
import fsspec

fs = fsspec.filesystem(
    "reference", 
    fo='s3://noaa-oar-cefi-regional-mom6-pds/northwest_atlantic/full_domain/hindcast/monthly/regrid/r20230520/ssh.nwa.full.hcast.monthly.regrid.r20230520.199301-201912.json',
    remote_protocol="s3", 
    remote_options={"anon":True}
)
 
ds = xr.open_dataset(fs.get_mapper(""), engine='zarr',backend_kwargs={"consolidated": False})

Additional output

No response

[chiaweh2]

update test : it seems by downgrading the zarr package from 3.1.1 --> 2.18.3 makes it work.

[AdeelH]

I'm running into the same issue. Passing target_options={"asynchronous": True} when creating the file system results in RuntimeError: Loop is not running.

Note: The problem happens with zarr-python v3. v2 works fine, but I'm trying to upgrade to v3.

File .../.venv/lib/python3.12/site-packages/fsspec/spec.py:81, in _Cached.__call__(cls, *args, **kwargs)
     79     return cls._cache[token]
     80 else:
---> 81     obj = super().__call__(*args, **kwargs)
     82     # Setting _fs_token here causes some static linters to complain.
     83     obj._fs_token_ = token

File .../.venv/lib/python3.12/site-packages/fsspec/implementations/reference.py:701, in ReferenceFileSystem.__init__(self, fo, target, ref_storage_args, target_protocol, target_options, remote_protocol, remote_options, fs, template_overrides, simple_templates, max_gap, max_block, cache_size, **kwargs)
    697 dic = dict(
    698     **(ref_storage_args or target_options or {}), protocol=target_protocol
    699 )
    700 ref_fs, fo2 = fsspec.core.url_to_fs(fo, **dic)
--> 701 if ref_fs.isfile(fo2):
    702     # text JSON
    703     with fsspec.open(fo, "rb", **dic) as f:
    704         logger.info("Read reference from URL %s", fo)

File .../.venv/lib/python3.12/site-packages/fsspec/asyn.py:118, in sync_wrapper.<locals>.wrapper(*args, **kwargs)
    115 @functools.wraps(func)
    116 def wrapper(*args, **kwargs):
    117     self = obj or args[0]
--> 118     return sync(self.loop, func, *args, **kwargs)

File .../.venv/lib/python3.12/site-packages/fsspec/asyn.py:76, in sync(loop, func, timeout, *args, **kwargs)
     73 # NB: if the loop is not running *yet*, it is OK to submit work
     74 # and we will wait for it
     75 if loop is None or loop.is_closed():
---> 76     raise RuntimeError("Loop is not running")
     77 try:
     78     loop0 = asyncio.events.get_running_loop()

RuntimeError: Loop is not running

[d-v-b]

cc @martindurant

[martindurant]

The support for FSMap objects was accepted into zarr without appropriate checks for compound filesystems like anything to do with kerchunk must be.

In this case, the filesystem is made in sync code (outside zarr), so the "target" filesystem, where the references live and which gets used immediately, should NOT be asynchronous. The "remote" filesystem will be called by zarr in async code, and SHOULD be asynchronous. But what about the referenceFS itself?? It gets created in sync code but used in async code, so I just don't think it can be made to work.

Note that this is even more complicated for lazy parquet references, which are loaded on demand, and so would

So we need one or all of the following solutions:

• the ability to pass a URL directly to zarr like "reference://::s3:..."; this may already work
• make sure that the engine="kerchunk" option for xarray does the right thing depending on which parts of the backend should be async.
• when zarr accepts an FSMap, have it pull apart all the components and set asynchronous or not, as required.

I thought these things were all expected to work already. Getting this right is important, not to lose the momentum that was begun by the kerchunk idea.

[AdeelH]

the ability to pass a URL directly to zarr like "reference://::s3:..."; this may already work

I just tried

ds = xr.open_zarr(
    "reference://::s3://...", 
    consolidated=False, 
    storage_options={
        "remote_protocol": "s3",
        "lazy": True
    }
)

with zarr 3.1.1 and it resulted in the same ValueError: Reference-FS's target filesystem must have same valueof asynchronous error. Same with xr.open_dataset(..., engine="kerchunk").

[keewis]

as mentioned in the xarray issue, using engine="kerchunk" without an explicit filesystem does work, so that's where I'd look for what to do to get it to work here, as well.

[AdeelH]

Thanks! The example in pydata/xarray#10597 (comment) worked for me, but only after I upgraded the related packages to the same versions as in the example:

xarray: 2025.7.1
fsspec: 2025.7.0
zarr: 3.1.1
s3fs: 2025.7.0
kerchunk: 0.2.9

Before upgrading the other packages I was getting the same error as above.

Perhaps zarr should constrain the required versions of those libraries?

[rsignell]

@martindurant asked me offline for my awkward workaround to access kerchunk references stored in parquet from both zarr=2 and zarr=3. Oof, okay! 🤓

I have a conditional for whether using zarr=v2 or zarr=v3 that determines which intake catalog entry to use:

intake_catalog_url = 'https://usgs-coawst.s3.amazonaws.com/useast-archive/coawst_intake.yml'
cat = intake.open_catalog(intake_catalog_url)

if zarr.__version__[0]=='2':
    dataset = 'COAWST-USEAST-zarr2' 
elif zarr.__version__[0]=='3':
    dataset = 'COAWST-USEAST-zarr3'
%%time
ds = cat[dataset].to_dask()

where my intake catalog looks like this:

description: 'intake catalog'
metadata:
  version: 1
  description: "Intake Catalog for data from USGS-COAWST model"

sources:
# If you are copy/paste-ing this entry to another catalog, you only need the
# lines from here down in your 'sources' section (be sure to indent as appropriate).
  COAWST-USEAST-zarr2:
    driver: intake_xarray.xzarr.ZarrSource
    description: 'USGS COAWST US East Coast and Gulf Coast Forecast Archive'
    args:
      urlpath: ['reference://']
      consolidated: false
      drop_variables: dstart
      decode_timedelta: false
      storage_options:
        target_options:
          anon: true
          skip_instance_cache: true
        fo: s3://usgs-coawst/useast-archive/combined.parq
        lazy: 'true'
        remote_options:
          anon: true
          skip_instance_cache: true
        remote_protocol: 's3'
  COAWST-USEAST-zarr3:
    driver: intake_xarray.xzarr.ZarrSource
    description: 'USGS COAWST US East Coast and Gulf Coast Forecast Archive'
    args:
      urlpath: ['reference://']
      consolidated: false
      decode_timedelta: false
      drop_variables: dstart
      storage_options:
        target_options:
          anon: true
        fo: s3://usgs-coawst/useast-archive/combined.parq
        lazy: true
        asynchronous: true
        remote_options:
          anon: true
          asynchronous: true
        remote_protocol: 's3'