Metabolomics troubleshooting

This page helps you diagnose failures across the 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