# 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.

### FileNotFoundError

```python
FileNotFoundError: No such file or directory: 'https://data.earthdatahub.destine.eu/era5/era5-single-levels-atmosphere-daily-utc-v0.zarr'
```

### NotImplementedError

```python
NotImplementedError: # V3 reading and writing is experimental! To enable support, set:
ZARR_V3_EXPERIMENTAL_API=1
```

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

```bash
pip show zarr
```

### uv

```bash
uv tree --package zarr --depth 0
```

### conda

```bash
conda list zarr
```

### python

```python
import zarr

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

To install the required Python dependencies, see [Environment setup](https://earthdatahub.destine.eu/docs/data-access.md#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](https://earthdatahub.destine.eu/docs/data-access.md#upgraded-access).

### ClientResponseError: 403 Forbidden

```python
ClientResponseError: 403, message='Forbidden', url='https://api.earthdatahub.destine.eu/climate-dt-2/IFS-NEMO-SSP3-7.0-sfc-hourly-standard-v0.zarr/zarr.json'
```

## 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](https://earthdatahub.destine.eu/docs/data-access.md#quotas).

### ClientResponseError: 429 Too Many Requests

```python
ClientResponseError: 429, message='Too Many Requests', url='https://data.earthdatahub.destine.eu/era5/era5-single-levels-atmosphere-daily-utc-v0.zarr/zarr.json'
```

## 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:

1. **Create a new API key** on the [Earth Data Hub dedicated page](https://earthdatahub.destine.eu/quota-api-keys#my-personal-access-tokens), and use the new key to access the data.
2. **Keep your current API key** and use the Earth Data Hub API domain instead: https://api.earthdatahub.destine.eu

### ClientResponseError: 426 Upgrade Required

```python
ClientResponseError: 426, message='Upgrade Required', url='https://data.earthdatahub.destine.eu/era5/era5-pressure-levels-v0.zarr/zarr.json'
```

## Unauthorized

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

1. **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.
2. **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](https://earthdatahub.destine.eu/docs/data-access.md#protected-datasets) section.

### ClientResponseError: 401, message=’Unauthorized’

```python
ClientResponseError: 401, message='Unauthorized', url='https://data.earthdatahub.destine.eu/private/test-dataset-v1.zarr/zarr.json'
```

## Debugging when using the local cache

The caching mechanism explained in the [Cache data locally](https://earthdatahub.destine.eu/docs/data-access.md#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:

### GroupNotFoundError

```python
GroupNotFoundError: No group found in store 'asyncwrapper::simplecache::https://edh:WRONG_API_KEY@data.earthdatahub.destine.eu/private/test-dataset-v1.zarr' at path ''
```

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**

```python
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**

```python
import xarray as xr

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