Appendix C — Troubleshooting Guide

Practical fixes for the errors that stop viromics pipelines most often. Each entry follows a Problem → Fix format. Start at the top of the list that matches your symptom, and change one thing at a time.

Read the last 20 lines of the log first

Most failures announce themselves. Before changing anything, run tail -n 20 logs/<step>.log (or tail -f for a live job). The real error is usually near the end, not in the wall of warnings above it.

C.1 `command not found`

Problem: the shell cannot find a tool — usually the wrong environment is active, or the tool was never installed.

Fix:

conda env list                       # which environments exist
conda activate viromics-core         # activate the right one
which fastqc                          # confirm the tool is on PATH

If which finds nothing, install the tool into that environment.

C.2 Conda solver is too slow or hangs

Problem: conda install spins for many minutes on “Solving environment”.

Fix: use mamba (or the libmamba solver) and strict channel priority.

conda install -n base -c conda-forge mamba          # one-time
mamba install -c conda-forge -c bioconda checkv     # use mamba from now on

# Or keep conda but switch its solver:
conda config --set solver libmamba
conda config --set channel_priority strict

C.3 Conda environment conflicts

Problem: two tools demand incompatible dependencies and refuse to co-install.

Fix: give each heavy tool its own environment instead of forcing them together.

mamba create -n checkv    -c conda-forge -c bioconda checkv
mamba create -n virsorter2 -c conda-forge -c bioconda virsorter=2

C.4 SRA download is slow or `prefetch` fails

Problem: prefetch/fasterq-dump stalls, times out, or errors on a public accession.

Fix: update the SRA Toolkit, run vdb-config once, prefetch before dumping, and raise the size cap. Retry — public mirrors are sometimes briefly unavailable.

mamba install -c conda-forge -c bioconda sra-tools
vdb-config --interactive          # accept defaults, set a cache dir once

prefetch --max-size 100g SRR000000                 # download the .sra first
fasterq-dump --split-files -e 12 -O raw_reads SRR000000
gzip raw_reads/SRR000000_*.fastq

# If prefetch keeps failing, fall back to a direct HTTPS/FTP mirror (ENA)
# or add:  --transport http

C.5 geNomad or CheckV database version mismatch

Problem: a run errors on the database, or results look wrong, because the installed tool version expects a different database version than the one on disk.

Fix: match the database to the tool. Re-download the database with the same tool version you are running, and point the tool at the exact folder.

genomad --version
genomad download-database $VIROME_DB/genomad        # re-fetch for this version
ls $VIROME_DB/genomad/genomad_db                     # confirm the versioned folder

checkv --version
# Re-download CheckV DB if the tool was upgraded:
checkv download_database $VIROME_DB/checkv
export CHECKVDB=$VIROME_DB/checkv/checkv-db-vX.Y      # set to the actual folder name

Keep the tool and its database in the same conda environment so upgrades stay in sync.

C.6 Database not found (CheckV / geNomad path errors)

Problem: the tool cannot locate its database directory.

Fix: confirm the environment variable and point to the folder that actually contains the DB.

echo $CHECKVDB
find $VIROME_DB/checkv  -maxdepth 2 -type d           # find the real checkv-db dir
find $VIROME_DB/genomad -maxdepth 2 -type d           # use the folder holding genomad_db

C.7 Disk full during assembly

Problem: assembly or mapping crashes with a write/“No space left on device” error. Assemblers create large temporary files.

Fix: check free space first, then free space, move temp to a bigger disk, and cap contig length.

df -h                                # find the full filesystem
du -sh ~/viromics_course/* databases/*   # find the big consumers

# Point MEGAHIT/temp at a larger disk and clean intermediates:
megahit -1 R1.fastq.gz -2 R2.fastq.gz -o /big/disk/out \
        --tmp-dir /big/disk/tmp --min-contig-len 1000 -t 12
rm -r out/intermediate_contigs        # remove after a successful run

C.8 Low memory during assembly

Problem: metaSPAdes exhausts RAM on a 32 GB machine.

Fix: switch to MEGAHIT, which is far more memory-efficient.

megahit -1 R1.fastq.gz -2 R2.fastq.gz -o out --min-contig-len 1000 -t 12

C.9 No contigs after assembly

Problem: the assembler finishes but produces an empty or tiny contig file.

Fix: check that reads survived trimming and read the assembler log.

seqkit stats trimmed_reads/*.fastq.gz     # are there reads left?
tail logs/samples_megahit.log             # what did the assembler say

C.10 Empty viral output

Problem: the viral prediction step returns no (or almost no) sequences.

Fix: the usual causes are biological or threshold-related:

the dataset genuinely has few viral reads;
contigs are too short to score confidently;
the score cutoff is too strict;
the database is missing or mismatched;
the assembly is highly fragmented.

Lower the minimum length for exploration, confirm the database, then return to stricter criteria for the final report.

C.11 Empty vOTU file

Problem: the vOTU FASTA has no sequences.

Fix: confirm the upstream viral FASTA exists and is non-empty.

seqkit stats $VIRAL_FASTA
grep -c "^>" $VIRAL_FASTA

C.12 Bowtie2 index error

Problem: mapping fails because the index is missing or the path is wrong.

Fix: rebuild the index and point Bowtie2 at the correct prefix.

bowtie2-build $VOTU_FASTA abundance/index/sample_votus
bowtie2 -x abundance/index/sample_votus -1 R1 -2 R2 -S out.sam

C.13 Figures script: R package not installed

Problem: make_figures.R (or another R step) stops with there is no package called '...'.

Fix: install the missing R packages into the environment you run R from, then re-run.

mamba install -n viromics-core -c conda-forge \
  r-ggplot2 r-pheatmap r-vegan r-dplyr r-readr r-tidyr

# Or from inside R for a one-off:
Rscript -e 'install.packages("pheatmap", repos="https://cloud.r-project.org")'

C.14 Python module missing

Problem: a Python figure or TPM script fails with ModuleNotFoundError.

Fix: install into the active environment.

mamba install -n viromics-core -c conda-forge pandas matplotlib numpy seaborn

# Troubleshooting Guide Practical fixes for the errors that stop viromics pipelines most often. Each entry follows a **Problem → Fix** format. Start at the top of the list that matches your symptom, and change one thing at a time. ::: {.callout-tip} ## Read the last 20 lines of the log first Most failures announce themselves. Before changing anything, run `tail -n 20 logs/<step>.log` (or `tail -f` for a live job). The real error is usually near the end, not in the wall of warnings above it. ::: ## `command not found` **Problem:** the shell cannot find a tool — usually the wrong environment is active, or the tool was never installed. **Fix:** ```bash conda env list # which environments exist conda activate viromics-core # activate the right one which fastqc # confirm the tool is on PATH ``` If `which` finds nothing, install the tool into that environment. ## Conda solver is too slow or hangs **Problem:** `conda install` spins for many minutes on "Solving environment". **Fix:** use `mamba` (or the libmamba solver) and strict channel priority. ```bash conda install -n base -c conda-forge mamba # one-time mamba install -c conda-forge -c bioconda checkv # use mamba from now on # Or keep conda but switch its solver: conda config --set solver libmamba conda config --set channel_priority strict ``` ## Conda environment conflicts **Problem:** two tools demand incompatible dependencies and refuse to co-install. **Fix:** give each heavy tool its own environment instead of forcing them together. ```bash mamba create -n checkv -c conda-forge -c bioconda checkv mamba create -n virsorter2 -c conda-forge -c bioconda virsorter=2 ``` ## SRA download is slow or `prefetch` fails **Problem:** `prefetch`/`fasterq-dump` stalls, times out, or errors on a public accession. **Fix:** update the SRA Toolkit, run `vdb-config` once, prefetch before dumping, and raise the size cap. Retry — public mirrors are sometimes briefly unavailable. ```bash mamba install -c conda-forge -c bioconda sra-tools vdb-config --interactive # accept defaults, set a cache dir once prefetch --max-size 100g SRR000000 # download the .sra first fasterq-dump --split-files -e 12 -O raw_reads SRR000000 gzip raw_reads/SRR000000_*.fastq # If prefetch keeps failing, fall back to a direct HTTPS/FTP mirror (ENA) # or add: --transport http ``` ## geNomad or CheckV database version mismatch **Problem:** a run errors on the database, or results look wrong, because the installed tool version expects a different database version than the one on disk. **Fix:** match the database to the tool. Re-download the database with the same tool version you are running, and point the tool at the exact folder. ```bash genomad --version genomad download-database $VIROME_DB/genomad # re-fetch for this version ls $VIROME_DB/genomad/genomad_db # confirm the versioned folder checkv --version # Re-download CheckV DB if the tool was upgraded: checkv download_database $VIROME_DB/checkv export CHECKVDB=$VIROME_DB/checkv/checkv-db-vX.Y # set to the actual folder name ``` Keep the tool and its database in the **same** conda environment so upgrades stay in sync. ## Database not found (CheckV / geNomad path errors) **Problem:** the tool cannot locate its database directory. **Fix:** confirm the environment variable and point to the folder that actually contains the DB. ```bash echo $CHECKVDB find $VIROME_DB/checkv -maxdepth 2 -type d # find the real checkv-db dir find $VIROME_DB/genomad -maxdepth 2 -type d # use the folder holding genomad_db ``` ## Disk full during assembly **Problem:** assembly or mapping crashes with a write/"No space left on device" error. Assemblers create large temporary files. **Fix:** check free space first, then free space, move temp to a bigger disk, and cap contig length. ```bash df -h # find the full filesystem du -sh ~/viromics_course/* databases/* # find the big consumers # Point MEGAHIT/temp at a larger disk and clean intermediates: megahit -1 R1.fastq.gz -2 R2.fastq.gz -o /big/disk/out \ --tmp-dir /big/disk/tmp --min-contig-len 1000 -t 12 rm -r out/intermediate_contigs # remove after a successful run ``` ## Low memory during assembly **Problem:** metaSPAdes exhausts RAM on a 32 GB machine. **Fix:** switch to MEGAHIT, which is far more memory-efficient. ```bash megahit -1 R1.fastq.gz -2 R2.fastq.gz -o out --min-contig-len 1000 -t 12 ``` ## No contigs after assembly **Problem:** the assembler finishes but produces an empty or tiny contig file. **Fix:** check that reads survived trimming and read the assembler log. ```bash seqkit stats trimmed_reads/*.fastq.gz # are there reads left? tail logs/samples_megahit.log # what did the assembler say ``` ## Empty viral output **Problem:** the viral prediction step returns no (or almost no) sequences. **Fix:** the usual causes are biological or threshold-related: - the dataset genuinely has few viral reads; - contigs are too short to score confidently; - the score cutoff is too strict; - the database is missing or mismatched; - the assembly is highly fragmented. Lower the minimum length for exploration, confirm the database, then return to stricter criteria for the final report. ## Empty vOTU file **Problem:** the vOTU FASTA has no sequences. **Fix:** confirm the upstream viral FASTA exists and is non-empty. ```bash seqkit stats $VIRAL_FASTA grep -c "^>" $VIRAL_FASTA ``` ## Bowtie2 index error **Problem:** mapping fails because the index is missing or the path is wrong. **Fix:** rebuild the index and point Bowtie2 at the correct prefix. ```bash bowtie2-build $VOTU_FASTA abundance/index/sample_votus bowtie2 -x abundance/index/sample_votus -1 R1 -2 R2 -S out.sam ``` ## Figures script: R package not installed **Problem:** `make_figures.R` (or another R step) stops with `there is no package called '...'`. **Fix:** install the missing R packages into the environment you run R from, then re-run. ```bash mamba install -n viromics-core -c conda-forge \ r-ggplot2 r-pheatmap r-vegan r-dplyr r-readr r-tidyr # Or from inside R for a one-off: Rscript -e 'install.packages("pheatmap", repos="https://cloud.r-project.org")' ``` ## Python module missing **Problem:** a Python figure or TPM script fails with `ModuleNotFoundError`. **Fix:** install into the active environment. ```bash mamba install -n viromics-core -c conda-forge pandas matplotlib numpy seaborn ```

C.1 command not found

C.2 Conda solver is too slow or hangs

C.3 Conda environment conflicts

C.4 SRA download is slow or prefetch fails

C.5 geNomad or CheckV database version mismatch

C.6 Database not found (CheckV / geNomad path errors)

C.7 Disk full during assembly

C.8 Low memory during assembly

C.9 No contigs after assembly

C.10 Empty viral output

C.11 Empty vOTU file

C.12 Bowtie2 index error

C.13 Figures script: R package not installed

C.14 Python module missing

C.1 `command not found`

C.4 SRA download is slow or `prefetch` fails