Troubleshooting#

Understand common errors and how to solve them.

Zarr v3 compatibility issues#

If the dataset URL is correct but you get a FileNotFoundError or NotImplementedError when opening a dataset, your Zarr library may not support the Zarr v3 format used by Earth Data Hub.

If you are using Python, make sure you have zarr-python 3.0 or later installed.

You can check your installed version in several ways:

pip

pip show zarr

uv tree --package zarr --depth 0

conda

conda list zarr

python

import zarr

print(f"Zarr Version: {zarr.__version__}")

To install the required Python dependencies, see Environment setup.

Restricted access#

If the dataset URL and API key are correct but you receive a ClientResponseError: 403 Forbidden, Earth Data Hub has successfully authenticated you, but your account does not have permission to access that dataset.

Some datasets, including those in the Destination Earth Climate Adaptation Digital Twin (Climate DT) collection, require additional permissions.

To request access, follow the instructions in Upgraded access.

Exhausted quota#

If you receive a ClientResponseError: 429 Too Many Requests, Earth Data Hub has successfully recognised your account, but you have used all of your available requests for the month.

You will need to wait for your quota to reset before accessing more data. To learn more about quotas and how to make the most of them, see Quotas.

API key needs to be updated#

If you see the error ClientResponseError: 426 Upgrade Required, it means that your API key cannot be used with the API domain you are currently accessing.

This can happen if you created your API key directly on the DestinE platform and are using the https://data.earthdatahub.destine.eu domain to access the data.

You can fix this in two ways:

Create a new API key on the Earth Data Hub dedicated page, and use the new key to access the data.
Keep your current API key and use the Earth Data Hub API domain instead: https://api.earthdatahub.destine.eu

Unauthorized#

If you see the error ClientResponseError: 401, message='Unauthorized', the two most likely scenarios are:

You are adding your token directly to the URL: in this case check that the token you use is correct and that you are using f-string correctly if you do.
You are using a .netrc file: in this case, besides checking the credentials in your .netrc file, a common error if you use Xarray / Zarr is to forget to add the storage_options={"client_kwargs": {"trust_env": True}} keyword argument to force the use of that identification file.

For full instructions on how to access protected datasets and configure your credentials, see the Access protected datasets section.

Debugging when using the local cache#

The caching mechanism explained in the Cache data locally section can sometimes make it harder to understand what went wrong.

When using the local cache, you may get a generic error such as GroupNotFoundError, which doesn’t necessarily tell you the actual cause of the problem. For example, you might see the following error:

If an error occurs while using the local cache, it is recommended to try the same request without using the cache. This can provide a more detailed error message and help identify the cause of the problem.

The following example shows the code with the cache enabled:

Cache enabled#

import xarray as xr

xr.open_dataset(
    "asyncwrapper::simplecache::https://edh:WRONG_API_KEY@data.earthdatahub.destine.eu/private/test-dataset-v1.zarr",
    storage_options={
        "simplecache": {"cache_storage": "./edh_cache/"},
        "asyncwrapper": {"asynchronous": True},
    },
    chunks={},
    engine="zarr",
)

The same request without the cache looks like this:

Cache disabled#

import xarray as xr

xr.open_dataset(
    "https://edh:WRONG_API_KEY@data.earthdatahub.destine.eu/private/test-dataset-v1.zarr",
    chunks={},
    engine="zarr",
)