2 General Troubleshooting

Important Note!! This handbook was written exclusively for people working at the RIVM (especially people at IDS). Some of the parameters or the way to run the pipeline would need to be changed for external people. Refer to the README section on the GitHub page of the corresponding pipeline. The pipelines that are enlisted as available through the internal GitLab from the RIVM are not accessible for external people. This might change in the future but for now that is the case. Equally, although the team would love to help external people to use our pipelines, we cannot give the personalized and fast-responding help that we give to people at the RIVM. If you do need help please write an Issue in the corresponding GitHub repository and we will try to help as soon as possible.

2.1 Solving problems when installing a pipeline or activating a pipeline environment

You should follow the instructions to set up conda before using any of our pipelines. If you did not do that, you may run into some issues and cryptic error messages. One of the most common error messages happens when you try to do conda activate <pipeline_env> where is the name of the environment especific to the pipeline you are using. The error message will say something like this:

CommandNotFoundError: Your shell has not been properly configured to use 'conda activate'.
To initialize your shell, run

    $ conda init <SHELL_NAME>

First you need to follow the instructions to set up conda and try installing the pipeline again. However, if you had already tried making some environments before following the conda configuration steps, your issue might not be solved. Specifically, when you try to use conda activate <env_name> you may get this error message now:

Could not find conda environment: <env_name>
You can list all discoverable environments with `conda info --envs`.

It is likely that you already made a conda environment but in the wrong place and conda cannot make the right one without you deleting the old (misplaced) one. In that case we need to find the wrong one and delete it. For that please type:

conda env list

This command will show you a list of your current environments. The result in the command line will look something like this:

# conda environments:
#
base                  *  /mnt/miniconda
                         /home/<username>/.conda/envs/<env_pipeline>
mamba                    /home/<username>/.conda/envs/mamba

You probably can notice that the paths that are in the second column do not correspond to what you would expect as explained in the instructions to set up conda. Instead, some of your environments were made in the /home/<username>/.conda folder and that is precisely the one we need to delete.

Note: DO NOT DO ANYTHING WITH THE base environment. That one is always placed in a different path.

To delete the wrong environments just type:

rm -rf /home/<username>/.conda

Note: Replace /home/<username>/.conda by the conda folder where the environments were meade. MAKE SURE TO INCLUDE THE FULL PATH NAME UP TO THE .conda FOLDER, OTHERWISE YOU COULD BE DELETING ESSENTIAL FOLDERS IN YOUR DESKTOP. Please ask a bioinformatician for help if you are unsure about how to do this step.

Note2: You must realize that this will delete ALL your previous conda environments (also the ones unrelated to the Juno pipelines.

This step might take a while because the folder usually contains many small files. However, after this step is done, you can try to install the pipeline again (making the new environments) according to the instructions of the pipeline you are using. If everything went fine, the conda activate <pipeline_env> command should work fine now. If you wonder how do you know whether this command worked or not, you can just look at your command line.

Before activating an environment it should look like this:

(base) [hernanda@rivm-biohn-l05p rondzendingen]$
  • Look at the word (base) at the beginning of the line.

After running the conda activate <pipeline_env> command it should look like this:

(<pipeline_env>) [hernanda@rivm-biohn-l05p rondzendingen]$
  • The name of the environment you just activated should now appear at the beginning of the line (<pipeline_env>).

Also, when you do conda env list you should see the correct paths (/mnt/scratch_dir/<username>/conda) for your environments:

# conda environments:
#
base                  *  /mnt/miniconda
<env_pipeline>           /mnt/scratch_dir/<username>/conda/envs/<env_pipeline>
mamba                    /mnt/scratch_dir/<username>/conda/envs/mamba

2.2 Failure when installing master environment

Sometimes the installation does not work because of the settings of Linux. The installation always takes some minutes in which a message saying Solving environment... might appear on the screen. However, if this step takes too long (for instance 30 min or more) please abort the step by pressing Ctrl + C and/or Ctrl + Z (sometimes you need to press repeateadly). In such cases, please change the necessary settings with this command:

conda config --set channel_priority false

Then try to run the pipeline and install the master environment again.

2.3 Failure to make a sample sheet or to find input directory

There are few reasons why this could happen:

  • Your path (all the folders that lead to your input directory) contains spaces or unrecognized characters.

  • You mis-spelled something in your path or gave the wrong path. Especially while working in Linux, it is common to forget a slash (“/”) at the beginning of a full path. For instance: /mnt/scratch_dir/<my_folder>/<my_data>/.

  • Your files might have the incorrect format and/or extension. Normally for all the files, standard names are accepted (for instance, .fastq.gz or .fastq for raw reads and .fasta for fasta files). Please make sure that your files have the correct and “classical” extensions.

  • Your input directory does contain the expected files, but they are placed in sub-folders. Most pipelines expect all input files to be together in one folder instead of scattered in sub-folders. The only exception is when you use output from a previous pipeline (for instance, Juno-assembly) into another pipeline. Please collect all your samples together in one folder.

2.4 Other problems or failing rules

The Juno pipelines are still in development which means that sometimes things fail. Before contacting me for help, please try these steps:

  1. Re-run the pipeline again and see if it goes further. If it does, please keep re-running the pipeline until your analysis is finished or it just doesn’t go further. Even if you are able to finish your analysis, just send me an email afterwards (see step 3) so I can check what happened.
  2. Download the pipeline again and start from the beginning of this handbook. Sometimes the issue has been resolved in newer versions of the pipeline.
  3. Collect your logging files and contact me. Please inform me about bugs/errors via e-mail sending also your log files and the path where I can find your input directory and the pipeline. No screenshots are necessary. Note that if you do not send this information, I will not be able to help you and your and my work will be delayed.