Trouble shooting
=====

This chapter contains a collection of common errors and their solutions.

* ``snakemake: command not found``: 

  * Did you install the cd2es environment and activated it before executing snakemake?

* ``sh: 1: cdo: not found``: 

  * The setup of the climate data processing tool *cdo* did not work correctly. Did you correctly execute all installation scripts? 
  * If you did and the error persists, look into :ref:`installation` to install *cdo* manually.

* ``ValueError: unrecognized chunk manager dask - must be one of: []``

  * the python package dask, which is used to handle large amounts of climate data is not installed correctly
  * that happens sometimes, it often can be fixed by reinstalling dask via ``pip install dask`` (when the cd2es environment is activated)

* ``Exception: No climate data available with the given parameters. Check model name and the cordex parameter in the config.``
    
  * The combination of climate variable, climate model and RCP does not exist. Compare the parameters given in the config (under ``scenario`` and ``cordexParameters``) and check whether the combination exisits on https://esgf-data.dkrz.de/search/cordex-dkrz/

* ``requests.exceptions.SSLError`` in the ``downloadEra5`` rule

  * error in the authentification at the copernicus climate data store
  * Did you register at https://cds.climate.copernicus.eu/?
  * Did you make a mistake when typing in your credentials?
  * Is ``loginDataAsParams`` activated in the config? Then you must give your credentials via the command line (see :doc:`config` for more infos). 
  
* Snakemake terminates without giving an indication for the type of error: 

  * often memory related, try diminishing ``mem_mb`` or enlarging ``numberOfChunks`` in the ``config``

* ``Unable to allocate memory``, ``process died with <Signals.SIGKILL: 9>``: 

  * not enough RAM, try diminishing ``mem_mb`` to execute less processes at the same time or enlarging ``numberOfChunks`` in the ``config``

* ``time-out, to allocate more time, change maxTime parameter in config`` or ``process returned non-zero exit status 50``:
  
  * execution of rule exceeded time limits
  * sometimes, the parallelized computations within the tool with dask get stuck, therefore, there is a time limit on all complicated rules
  * if a rule exceeds the time limit, it gets killed and restarted - therefore this error might exist but the tool can still successfully complete (if the restarted process does not get stuck)
  * the error code for a rule killed by the time out is 50 (sometimes the display of the written warning does not work)
  * the time limit is given by the ``maxTime`` in the config
  * if all retries of a rule are killed with the out of time error, enlarge the time limit to make sure it is only activated in case of a stuck process

* Error in ``rule downloadEra5`` without information on the error: 

  * Did you register with the copernicus climate data store? 
  * See :ref:`prereq` for more information. 
  * If you have problems with setting up the .cdsapirc in the home folder, you can also give your copernicus climate data store credentials directly in the config (``giveCdsCredentialsInConfig``).

* Downloads of era5 or cordex data fail (e.g. with ``Gateway Time-out``, ``Read timed out.`` or ``500 Server Error``) 
    
  * This is often not related to the tool or your execution but the download server which has down times or failures from time to time. Wait a little and try again later and contact either the Copernicus data store (for era5 data) or the ESGF (for cordex data) if the problem persists.

* ``No rule to produce {filename}``:

  * The file you are trying to produce cannot be created by snakemake workflow. 
  * If you have specified a filename, check whether there is a rule that produces your desired file and check your spelling. Check the wildcards you inserted by checking ``wildcard_constraints`` in line 12 of the snakefile.
  * If you run the tool without a specified filename, check the information in the section ``scenario`` of the config and whether they are correct (either by checking the comments in the config or by checking ``wildcard_constraints`` in line 12 of the snakefile).
  * If you are on Windows and having a snakemake version < 8, you need to add ``--keep-target-files`` to your command line to resolve this problem. 

* ``Permission denied``

  * Is any of the output files still open in another programme?