Troubleshooting

This page provides solutions to the most common MetaGraph issues.

Installation

See Installation for platform-specific troubleshooting.

Quick fixes:

  • Conda fails: conda install -c bioconda metagraph or fresh environment

  • Docker error: pull the latest image: docker pull ghcr.io/ratschlab/metagraph:master

  • Compiler too old: Need GCC 9+ or Clang 9+

Memory Issues

Out of memory

Symptoms: Process killed, allocation failed

Solutions:

  1. Use disk swap (recommended):

    # Graph construction
metagraph build --disk-swap /tmp --mem-cap-gb 50 input.fa

# Annotation
metagraph annotate --disk-swap /tmp --mem-cap-gb 10 ...

  2. Process files separately:

    metagraph annotate --separately -p 4 --threads-each 9 ...

  3. Estimate memory needs:

    • Graph: ~3 bits/k-mer

    • Annotation: ~0.5 bits/k-mer/label

    • RowDiff transform: graph + 2× annotation

Memory cap ignored

Issue: MetaGraph uses more RAM than --mem-cap-gb specifies

Solution: Lower the cap value – it is rather a buffer size than a strict limit

Annotation Issues

Missing k-mer counts file

Error: No k-mer counts found ...

Cause: Missing .kmer_counts.gz file

Solution:

# Build weighted graph
metagraph build -k 31 --count-kmers -o graph input.fa

# Transform creates both files
metagraph transform --to-fasta -o contigs graph.dbg
# Creates: contigs.fasta.gz + contigs.kmer_counts.gz

Annotation fails

Issue: Runs out of memory

Solutions:

  1. Use disk swap:

    metagraph annotate --separately --disk-swap /tmp \
    --mem-cap-gb 10 -o annotation genome.fasta.gz

  2. Annotate multiple files separately:

    cat *.fasta.gz | metagraph annotate --separately \
    --disk-swap /tmp \
    --mem-cap-gb 10 -o ./out/annotation

  3. Annotate contigs instead of raw sequences:

    # Build sample graph
metagraph build -k 31 -o sample.graph genome.fa

# Extract contigs
metagraph transform --to-fasta -o sample.contigs sample.graph.dbg

# Annotate with coordinates
metagraph annotate -i joint.dbg -o annotation sample.contigs.fasta.gz

Transform Errors

RowDiff transform fails

Error: Graph required for row-diff transform

Solution: Always provide graph with -i to the RowDiff transform:

BRWT out-of-memory

Solution: Reduce subsampling or use disk swap:

# Option 1: Reduce subsampling
metagraph transform_anno --anno-type brwt --subsample 500000 \
    --greedy -o annotation input.column.annodbg

# Option 2: Disable temp files if there are too many columns (>1M)
metagraph transform_anno --anno-type brwt --disk-swap "" \
    --greedy -o annotation input.column.annodbg

Missing transform output

Issue: kmer_counts.gz not created

Cause: Graph not weighted

Solution: Build with --count-kmers:

metagraph build -k 31 --count-kmers -o graph input.fa
metagraph transform --to-fasta -o contigs graph.dbg
# Now creates both .fasta.gz and .kmer_counts.gz

Alignment Issues

Empty sequence error

Error: Assertion fails on empty sequence

Solution: Filter empty sequences:

seqkit seq -m 1 input.fa > filtered.fa
metagraph align -i graph.dbg filtered.fa

Reverse complement fails

Issue: RC alignment doesn’t work

Solution: Use canonical or primary graph:

# Build canonical
metagraph build -k 31 --mode canonical -o graph input.fa

# Transform to primary
metagraph transform --to-fasta --primary-kmers -o contigs graph.dbg
metagraph build -k 31 --mode primary -o graph_primary contigs.fasta.gz

API Issues

Python API Connection Fails

Error: RuntimeError or connection refused

Solution:

  1. Ensure server is running:

    metagraph server_query -i graph.dbg -a annotation.annodbg \
    --port 5555 -p 10

  2. Use correct connection:

    from metagraph.client import GraphClient

# For local server
client = GraphClient('localhost', 5555, api_path='')

# Test connection
labels = client.column_labels()
print(f"Connected! {len(labels)} labels")

API not installed

Error: ModuleNotFoundError: No module named 'metagraph'

Solution:

pip install -U "git+https://github.com/ratschlab/metagraph.git#subdirectory=metagraph/api/python"

Docker

libhts.so.3 error: Pull latest image:

docker pull ghcr.io/ratschlab/metagraph:master

Permission denied: Add user to docker group or use sudo

Performance Tips

Speed up construction

  1. Use all cores: -p $(nproc)

  2. Pre-process with KMC: Faster k-mer counting

  3. Use SSD for disk swap: Faster I/O

  4. Process different samples in parallel: GNU parallel or workflow manager

Reduce Index Size

  1. Use primary graph: 50% smaller than canonical

  2. Use RowDiff<BRWT>: 10-20% of column size

  3. Filter k-mers: with KMC (e.g., kmc -ci5) or graph cleaning

  4. Compress graph: metagraph transform --state small

Getting Help

If your issue isn’t listed:

  1. See FAQ: Frequently Asked Questions

  2. Search in GitHub issues

  3. Prompt AI with this documentation and ask for help

  4. Open an issue on GitHub https://github.com/ratschlab/metagraph