---
title: Metagenomics troubleshooting
description: >-
  Resolve classification failures, low-quality results, diversity calculation
  issues, and differential abundance errors.
tags:
  - metagenomics
  - troubleshooting
---

This page helps you diagnose the problems you hit in [metagenomics](/docs/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