Metagenomics troubleshooting

This page helps you diagnose the problems you hit in metagenomics analysis — low classification rates and empty profiles, diversity values that look wrong, differential abundance results with too few or too many hits, and FASTQ upload issues.

Metagenomics troubleshooting

Classification returns very few classified reads

Symptom: classification_rate is under 20%.

Fixes:

• Check the reference database. standard covers general bacterial/archaeal/viral metagenomics; for 16S amplicon data, switch to silva or greengenes
• Try a different classification method (kraken2, centrifuge, kaiju) — sensitivity varies by algorithm and read length
• Verify read quality. Very short reads (< 50 bp) or reads with many ambiguous bases (N) reduce classification accuracy
• Host contamination can inflate unclassified reads. For human-associated samples, consider host read removal upstream
• Lower confidence (default 0.1) to accept less-confident assignments, or raise it to see if the rate is being inflated by weak calls

Classification takes too long

Symptom: Classification job runs for more than 30 minutes without completing.

Fixes:

• Large FASTQ files take longer. For initial exploration, subsample to 1 million reads
• Check that the file uploaded successfully. Partial or corrupted uploads can cause the classifier to hang
• If using paired-end reads, ensure both fastq_uri and fastq_r2_uri point to matching, complete files

Profile looks wrong or empty

Symptom: metagenomics_profile returns low richness or an empty phylum_abundances map.

Fixes:

• Try the other profiling method (metaphlan, bracken, motu) — each uses a different reference marker set and will miss organisms the others catch
• Very shallow sequencing (< 100,000 reads) may not hit enough marker genes for confident profiling
• For 16S amplicon data, profile with metagenomics_classify against silva/greengenes instead — the profiling method here targets shotgun data
• Check that the input file is FASTQ format (not FASTA); the profiler expects quality scores for read filtering

Diversity values seem wrong

Symptom: Shannon diversity is 0 or unexpectedly low/high.

Fixes:

• A Shannon index of 0 means only one taxon is present in that sample's profile
• Verify the abundance_table_uri actually points at the intended metagenomics_profile output and not an empty or stale job result
• For zero-dominated communities, Chao1 may return very large estimates — expected when many singleton taxa are present

Beta distances look implausible

Symptom: beta_distances values don't match the expected similarity between samples.

Fixes:

• Confirm beta_method — bray_curtis (default), unifrac, and jaccard measure different things and aren't directly comparable to each other
• Ensure every sample was profiled with the same method and resolution — comparing a MetaPhlAn genus-level profile against a Bracken species-level profile will distort distances
• Ensure the sample IDs in your metadata file match the sample IDs the profiling step produced

Differential abundance returns no significant taxa

Symptom: significant_taxa is empty (nothing below adjusted p-value 0.05).

Fixes:

• Check sample size. Fewer than 5 samples per group severely limits statistical power for all methods
• Try a different method (ancombc, aldex2, maaslin2) — sensitivity to compositional effects varies by algorithm
• Verify that the contrast string and the metadata CSV's condition column values actually match (a typo'd contrast silently returns nothing)
• The absence of significant taxa may be biologically real

Differential abundance returns too many significant taxa

Symptom: Hundreds of taxa are significant, which seems biologically implausible.

Fixes:

• Try ancombc or aldex2 if you started with maaslin2 (or vice versa) — compositional-data methods differ in how conservative they are
• Check for batch effects or confounders. If treatment and control samples were processed on different days, batch effects can inflate false positives
• Sort significant_taxa by abs(log2_fold_change) and focus on the largest effects rather than the full list

File upload issues

Symptom: FASTQ file upload fails or times out.

Fixes:

• Ensure the file is gzip-compressed (.fastq.gz). Uncompressed FASTQ files are much larger and may exceed upload limits
• Check that the file is not corrupted. A truncated gzip file will fail to decompress
• For paired-end data, both R1 and R2 files must be uploaded before starting classification

Getting help

If issues persist:

1. Check the tool error message for specific suggestions
2. Verify your input file format and quality before uploading
3. Start with a small subset of reads (1M) to test parameters before running the full dataset
4. Describe the issue to Ivy

Read next