---
title: Genomics troubleshooting
description: >-
  Resolve query failures, empty results, identifier mismatches, and
  cross-database linking issues.
tags:
  - genomics
  - troubleshooting
---

This page helps you diagnose the failures you hit when querying [genomics](/docs/genomics) databases — empty results, gene and variant identifiers that won't resolve, cross-database links that come back empty, malformed record fetches, and rate-limit or timeout errors.

## Genomics troubleshooting

## Gene not found in Ensembl

**Symptom**: "Unknown error" or empty result when looking up a gene.

**Fixes**:

- Check the gene symbol spelling. Use official HGNC symbols (e.g., `TP53` not `p53`)
- If using an Ensembl ID, ensure it starts with the correct prefix (`ENSG` for human, `ENSMUSG` for mouse)
- Make sure the species matches your gene. Human is the default; name another species in your prompt
- Some non-coding genes and pseudogenes may not have Ensembl entries. Ask Ivy to search NCBI Gene instead

## No KEGG pathway results

**Symptom**: Zero results returned from KEGG pathway search.

**Fixes**:

- Try broader search terms. KEGG pathway names may differ from common names (e.g., "p53 signaling" instead of "TP53 pathway")
- Check the organism. The default is human (`hsa`); name mouse (`mmu`), rat (`rno`) or another organism in your prompt
- Ask Ivy to search KEGG genes rather than pathways when you are searching by gene symbol
- Some recently discovered pathways may not yet be in KEGG. Try Reactome as an alternative

## ClinVar returns no variants

**Symptom**: Zero variants found for a gene query.

**Fixes**:

- Ensure correct gene symbol spelling (case-sensitive)
- For rsID queries, include the `rs` prefix (e.g., `rs334` not `334`)
- HGVS expressions must match exactly (check transcript version)
- Ask without a significance filter to see all variants, then narrow down
- Some genes have very few clinically reported variants. This is expected for non-disease-associated genes

## OpenTargets query fails

**Symptom**: Error or empty results from OpenTargets associations.

**Fixes**:

- Gene symbols are resolved to Ensembl IDs automatically. If resolution fails, provide the Ensembl ID directly (e.g., `ENSG00000146648` for EGFR)
- For disease queries, try using the EFO ID (e.g., `EFO_0000685`) instead of a disease name
- The default minimum score (0.1) may exclude weak associations. Ask for a lower cutoff, such as 0.01, for comprehensive results
- OpenTargets covers primarily human diseases. Non-human queries will not return results

## Entrez Link returns zero linked records

**Symptom**: No linked records found between databases.

**Fixes**:

- Verify that the source IDs are valid for the source database (ask Ivy to search that database to confirm)
- Not all link paths exist. For example, `taxonomy_structure` is not a standard link. Check the [common link paths](/docs/genomics/inputs) table
- Some records may not have cross-references. A gene may not have any associated PDB structures
- Leave the link path unspecified so Ivy auto-detects the available links

## Entrez Fetch returns wrong format

**Symptom**: Content appears garbled or in an unexpected format.

**Fixes**:

- Not all formats work with all databases. FASTA only works for sequence databases (protein, nucleotide)
- For gene records, ask for XML instead of FASTA
- For PubMed records, ask for the abstract for readable text
- Large records (>50,000 characters) are truncated. Check the `truncated` field in the output

## MeSH term not resolved

**Symptom**: "MeSH term not found" even for common medical concepts.

**Fixes**:

- MeSH uses specific controlled vocabulary. Ask Ivy to suggest matching MeSH headings
- Check spelling carefully. MeSH terms use American English ("tumor" not "tumour")
- Some concepts are entry terms (synonyms) rather than main headings. The suggestion mode will show the official heading
- Very recent concepts may not yet have MeSH descriptors. Check the [MeSH Browser](https://meshb.nlm.nih.gov/) directly

## Reactome returns no pathways

**Symptom**: Zero pathways found for a search term.

**Fixes**:

- Reactome pathway names may differ from other databases. Try broader terms
- Check the species (the default is *Homo sapiens*). Reactome has limited coverage for non-model organisms
- If you have a Reactome ID (e.g., `R-HSA-109582`), search by ID for a direct lookup
- For gene-based searches, the gene symbol must match Reactome's naming convention

## Rate limiting or timeout errors

**Symptom**: "Request failed" or timeout errors.

**Explanation**: NCBI E-utilities enforce rate limits (3 requests/second without API key, 10/second with key). All genomics tools respect these limits automatically.

**Fixes**:

- Wait a few seconds and retry. The rate limiter queues requests automatically
- If querying multiple genes, Ivy will space requests appropriately
- Large result sets (>50 records) may take longer. Ask for fewer results if speed is important
- Ensembl, KEGG, OpenTargets, and Reactome have independent rate limits and are rarely throttled

## Getting help

If issues persist:

1. Check the tool error message for specific suggestions
2. Verify your identifier format matches the expected input
3. Try the same query on the database's web interface to confirm data availability
4. Describe the issue to Ivy

## Read next