Troubleshooting Guide

# System resources
free -h                              # Memory
df -h                                # Disk space
nproc                                # CPU cores
ulimit -a                            # Resource limits
 
# Environment
which python
python --version
conda list | grep -E "kraken2|humann|qiime"
echo $PATH
 
# Installation check
./scripts/verify_installation.sh
 
# Database check
ls -la /path/to/kraken2_db/*.k2d
ls -la /path/to/kneaddata_db/*.bt2
 
# Log analysis
tail -f logs/analysis.log
grep -i "error\|fatal\|exception" logs/*.log

Problem occurs
      ↓
Check logs (logs/error.log)
      ↓
┌─────────────┴─────────────┐
↓                           ↓
Installation Error      Runtime Error
↓                           ↓
Verify dependencies    Check input data
↓                           ↓
Reinstall if needed    Adjust parameters

CondaEnvException: Pip failed
ResolvePackageNotFound

# 1. Update conda
conda update -n base -c conda-forge conda
 
# 2. Clean cache
conda clean --all -y
 
# 3. Install mamba (faster solver)
conda install -n base -c conda-forge mamba
 
# 4. Create environment with mamba
mamba env create -f environment.yml
 
# 5. If still failing, try sequential installation
conda create -n micos-2024 python=3.9
conda activate micos-2024
mamba install kraken2 kneaddata humann
pip install -e .

permission denied while trying to connect to Docker daemon

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
 
# Verify
docker run hello-world
 
# If still failing, check socket permissions
ls -la /var/run/docker.sock

MemoryError: Unable to allocate array
OSError: Cannot allocate memory

# Increase swap space
sudo fallocate -l 16G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
 
# Or reduce parallelism
export CONDA_SOLVER_THREADS=2
mamba env create -f environment.yml

Found conflicts! Looking for incompatible packages.

# Use fresh environment
conda env create -f environment.yml --force
 
# Or install in specific order
conda create -n micos-2024 python=3.9
conda activate micos-2024
conda install -c bioconda -c conda-forge kraken2
conda install -c bioconda -c conda-forge humann
conda install -c bioconda -c conda-forge kneaddata
pip install -e .

FileNotFoundError: [Errno 2] No such file or directory: '/path/to/kraken2_db'
kraken2: database does not contain necessary file hash.k2d

# Check database files
ls -la /path/to/kraken2_db/
 
# Verify required files exist
ls hash.k2d opts.k2d taxo.k2d  # For Kraken2
ls *.bt2  # For KneadData/Bowtie2

# 1. Update configuration
nano config/databases.yaml
 
# 2. Verify paths
echo "kraken2: /correct/path/to/kraken2_db"
 
# 3. If database missing, download
# See Installation Guide for database download

yaml.scanner.ScannerError: mapping values are not allowed here
ParserError: while parsing a block mapping

# Check YAML syntax
python -c "import yaml; yaml.safe_load(open('config/analysis.yaml'))"
 
# Or use yamllint
yamllint config/analysis.yaml

ValueError: Sample metadata file format error
Error: Column 'sample-id' not found

# Convert CSV to TSV
sed 's/,/\t/g' samples.csv > samples.tsv
 
# Verify format
head -3 samples.tsv | cat -A
# Should show tabs (^I) not commas
 
# Validate column names
head -1 samples.tsv | tr '\t' '\n' | nl

kraken2: unable to open database
Error reading in hash table

# 1. Check database integrity
ls -lh /path/to/kraken2_db/
# Should have: hash.k2d, opts.k2d, taxo.k2d
 
# 2. Check permissions
ls -la /path/to/kraken2_db/
 
# 3. Verify memory
free -h
# Database requires ~size of database in RAM
 
# 4. Re-download if corrupted
kraken2-build --download-taxonomy --db /new/path

Error: Bowtie2 failed
Error: could not open index file

# Check index files
ls /path/to/kneaddata_db/*.bt2
# Should have: .1.bt2, .2.bt2, .3.bt2, .4.bt2, .rev.1.bt2, .rev.2.bt2
 
# Re-download if needed
kneaddata_database --download human_genome bowtie2 /new/path
 
# Check disk space
df -h

# Use faster settings in config
functional_annotation:
  humann:
    diamond_options: "--fast"
    threads: 8
    # Use UniRef50 instead of UniRef90
    protein_database: "/db/uniref50"

ValueError: BIOM file appears to be empty

# Check BIOM file
biom summarize-table -i feature-table.biom
 
# If empty, regenerate
kraken-biom *.report --fmt hdf5 -o new-table.biom
 
# Check Kraken2 reports
head *.report
# Should have classification data

resources:
  max_threads: 32
  max_memory: "64GB"
 
paths:
  temp_dir: "/fast_ssd/tmp"
 
taxonomic_profiling:
  kraken2:
    memory_mapping: true    # Faster but more RAM

# 1. Clean intermediate files
rm -rf results/*/intermediate/
rm -rf tmp/*
 
# 2. Compress outputs
gzip results/*/*.fastq
 
# 3. Enable auto-cleanup in config
quality_control:
  kneaddata:
    remove_intermediate: true
 
# 4. Use external storage
ln -s /external/storage/results results

# Reduce parallel jobs
resources:
  max_threads: 8    # Instead of 16+
  max_memory: "16GB"
 
# Disable memory mapping for Kraken2
taxonomic_profiling:
  kraken2:
    memory_mapping: false
 
# Use smaller database
databases:
  kraken2: "/db/minikraken2_v2_8GB"

# Lower confidence threshold
taxonomic_profiling:
  kraken2:
    confidence: 0.05
 
# Use broader database
databases:
  kraken2: "/db/kraken2_pluspf"  # Includes fungi/protozoa

quality_control:
  kneaddata:
    min_quality: 25      # Increase from 20
    min_length: 75       # Increase from 50

# 1. Check metadata for batch information
cut -f3 metadata.tsv | sort | uniq -c
 
# 2. Include batch in statistical model
# Use PERMANOVA with strata
qiime diversity beta-group-significance \
  --i-distance-matrix braycurtis.qza \
  --m-metadata-file metadata.tsv \
  --m-metadata-column group \
  --p-method permanova \
  --p-permutations 999 \
  --o-visualization results.qzv

# Check if earlier steps produced output
ls -lh results/quality_control/
ls -lh results/taxonomic_profiling/
 
# Check logs
tail logs/analysis.log

# Check if data exists
head results/taxonomic_profiling/*.report
 
# Regenerate manually
ktImportTaxonomy \
  -o new_krona.html \
  results/taxonomic_profiling/*.report
 
# Check browser console for JavaScript errors

# 1. Sample in metadata?
grep "Sample001" metadata.tsv
 
# 2. Input files exist?
ls data/raw_input/Sample001*.fastq.gz
 
# 3. Sample passed QC?
grep "Sample001" results/quality_control/kneaddata/*.log
 
# 4. Check for errors
grep -i "Sample001" logs/*.log | grep -i error

# Exit code 137 indicates OOM
dmesg | grep -i "killed process"
# Shows processes killed by OOM killer

**Environment**
- OS: [e.g., Ubuntu 20.04]
- Python: [e.g., 3.9.12]
- MICOS version: [e.g., 1.0.0]
- Installation method: [Docker/Conda/Source]
 
**Command**
```bash
# The exact command you ran

Full error message or relevant log excerpt

### Support Channels

| Channel | Best For | Response Time |
|:---|:---|:---:|
| [GitHub Issues](https://github.com/BGI-MICOS/MICOS-2024/issues) | Bug reports, feature requests | 1-3 days |
| [Discussions](https://github.com/BGI-MICOS/MICOS-2024/discussions) | Questions, best practices | 1-7 days |
| Documentation | Quick reference | Immediate |

---

<p align="center">
  <a href="/micos-2024/en/faq">→ View Frequently Asked Questions</a>
</p>