---
title: Metabolomics troubleshooting
description: >-
  Resolve preprocessing failures, annotation mismatches, differential analysis
  errors, and pathway enrichment issues.
tags:
  - metabolomics
  - troubleshooting
---

This page helps you diagnose failures across the [metabolomics](/docs/metabolomics) pipeline: preprocessing errors, low metabolite annotation rates, differential analysis that finds nothing significant, and pathway enrichment that maps no metabolites.

## Metabolomics troubleshooting

## Preprocessing fails with "Either mzml_key or peak_table_key is required"

**Symptom**: `metabolomics_preprocess` errors immediately.

**Fixes**:

- Upload a raw mzML/mzXML file, or a pre-processed peak table CSV, and pass its URI as `raw_data_uri`
- If you point the tool at a raw mzML file, note that full peak picking requires pyOpenMS server-side; the tool currently returns a stub summary (`features_detected: 0`) for raw mzML and does full statistics only for an uploaded peak table

## Preprocessing summary looks wrong (TIC median or feature counts are off)

**Symptom**: `tic_median`, `missing_value_rate`, or `features_detected` don't match what you expect.

**Fixes**:

- Preprocessing always applies TIC normalization and a log2 transform when given a peak table — there's no way to disable or swap this
- `missing_value_rate` counts exact-zero entries in your table. If your table encodes missing values differently (e.g., blank cells, `NA`), zero-fill them first
- Check that your peak table's first column is the feature ID (used as the index) and the remaining columns are per-sample intensities

## Low annotation rate

**Symptom**: `total_annotated` is much lower than `total_features`.

**Fixes**:

- `metabolomics_annotate` only queries the first 50 features in your table per run — for a larger feature table, split it into batches
- Feature IDs must encode a parseable m/z value (e.g., `mz_204.0899` or `M204.0899`). Feature IDs that don't parse as a number are always reported as `"unknown"`
- Widen `mass_tolerance_ppm` from the default 5 ppm to 10-15 ppm
- Try `databases: "all"` to search HMDB, LipidMaps, and KEGG together instead of a single database
- A `"putative_match"` only means the live HMDB mass-search API returned a hit for that m/z window — if the HMDB service is slow or unreachable, matches silently fail and the feature is reported as `"unknown"`

## Differential analysis finds no significant metabolites

**Symptom**: `total_significant` is 0.

**Fixes**:

- If you provide `metadata_file_uri`, the tool looks for a column literally named `group` — any other column name is ignored and the tool falls back to splitting your samples into two halves by column order
- With the fallback split, make sure your feature table's sample columns are already ordered by group, or the comparison is meaningless
- You need at least 2 samples per group (4 total) for the fallback split, or at least 2 groups represented in your metadata
- If most p-values are near 1.0, your two groups may not differ, or the input needs preprocessing (TIC normalization/log2) first

## Pathway enrichment returns no significant pathways

**Symptom**: `significant_pathways` is 0, or `total_features_with_mass` is 0.

**Fixes**:

- Pathway enrichment parses masses from your metabolite/feature IDs the same way annotation does (e.g., `mz_204.0899`) — HMDB or KEGG IDs alone (like `HMDB0000929`) won't parse to a mass and will be skipped. Check `total_features_with_mass` in the output
- Enrichment is tested against a small, curated set of ~10 common KEGG metabolic pathways (glycolysis, TCA cycle, amino acid metabolism, and similar) — a pathway outside this set can never appear in the results, regardless of `organism` or `id_type`
- `organism` only accepts `"hsa"` (human) or `"mmu"` (mouse); anything else is not supported
- Widen `mass_accuracy_ppm` if you expect matches but see none

## File upload or format errors

**Symptom**: The tool can't read your uploaded file.

**Fixes**:

- Peak tables and metadata files must be CSV, with the feature or sample ID as the first column (used as the table index)
- Excel files (.xlsx) are not supported — export as CSV first
- Ensure intensity columns contain only numbers; non-numeric placeholders (e.g., `"N/A"`) will break parsing

## Getting help

If issues persist:

1. Check the tool error message for specific details
2. Verify your input data format matches the expected columns
3. Try running with default parameters first, then customize
4. Describe the issue to Ivy

## Read next