Troubleshooting

Unsupported dataset: <...>

Raised by path_constructor.build_directory_path when files_query_options.dataset isn’t one of the keys zephyr knows about (era5_cds, era5-land_cds, cerra, cerra-land, cmip5, cmip6, cordex, cordex-reklies). Check for a typo, and see Supported Datasets for the exact expected value.

Missing key '<field>' in files_query_options necessary to build the directory path

The dataset builder for your chosen dataset needs a field that isn’t in your request. See the required-fields table in Request JSON Format for what each dataset expects (e.g. cordex needs institution, gcm, rcm, ensemble_member, … — cmip5 doesn’t need institution or grid but does need gcm and ensemble_member).

No file paths found. Check file fetcher and query options.

ProcessManager logs this and returns without writing any output when the directory built from files_query_options doesn’t match any files on /net/atmos/data. Common causes:

  • A field value that doesn’t exist for that dataset (wrong gcm, rcm, ensemble_member, scenario, spelling, or casing)

  • A start/end date range outside what’s actually stored

  • Running from a machine that doesn’t have /net/atmos/data mounted (see Installation — this only works on an IAC machine)

Permission or “path not found” errors on /net/atmos/data

Zephyr must run on a machine with /net/atmos/data mounted and readable — see Installation. Running the same command on a laptop or a GitHub-hosted CI runner will fail for this reason; that’s why tests/requests and real extractions both require an IAC machine (or the iacdipl-7.ethz.ch self-hosted runner used by CI, see Development).

Grid detection errors (LCC without regular coordinates)

fileload.py raises a ValueError if a file’s grid can’t be resolved to regular latitude/longitude coordinates (e.g. an LCC file missing the expected coordinate variables). This usually indicates an unexpected or malformed input file rather than something fixable via the request JSON — report it with the dataset and file path so the grid-handling logic in fileload.py/transform_lcc.py can be extended.

My zephyr-request GitHub issue is stuck or failed

That pipeline lives in a different repo — see its README for the processing stages and status labels, summarized in Using the Web Interface. Commenting rerun request on the issue re-triggers processing without needing a new issue.

uv: command not found

uv isn’t installed for your account yet (this is per-user, not system-wide). See the install step in Installation.