Troubleshooting¶
BioMCP depends on multiple public biomedical APIs, so transient source failures are expected. This guide focuses on practical triage for API failures, slow responses, and environment issues. Start with health checks, then narrow to the affected entity and source.
1) Validate connectivity first¶
Run API-level checks before debugging entity-specific commands:
If one source fails while others pass, the issue is usually upstream availability and not your local install.
2) MyGene / MyVariant intermittent failures¶
Gene and variant lookups rely on BioThings services (mygene.info, myvariant.info).
These services can intermittently return 5xx or timeout responses during peak traffic.
What BioMCP already does:
- Uses shared HTTP client timeouts (
connect_timeout=10s,timeout=30s) - Retries transient failures with exponential backoff (up to 3 retries)
- Uses HTTP cache to reduce repeat upstream calls
What to do when failures persist:
If --no-cache works while cached mode fails repeatedly, clear cache and retry:
3) ClinicalTrials.gov API v2 quirks¶
ClinicalTrials.gov search behavior can vary with complex query combinations and pagination tokens. The most common symptoms are empty pages after filters or unstable totals between repeated calls.
Recommended steps:
- Start with minimal filters (
-c,--limit) and add one filter at a time. - Use explicit
--source ctgovor--source ncito isolate source behavior. - Avoid changing both geographic and ESSIE filters in the same troubleshooting step.
Examples:
biomcp search trial -c melanoma --source ctgov --limit 5
biomcp search trial -c melanoma --source nci --limit 5
4) OpenFDA FAERS / recall pagination limits¶
OpenFDA-backed searches are currently capped by BioMCP at --limit <= 50 per request.
If you need more data, page your own workflow with narrower queries and repeated commands.
biomcp search adverse-event --drug pembrolizumab --limit 50
biomcp search adverse-event --type recall --classification "Class I" --limit 50
If you have an OpenFDA API key, export it to increase quota stability:
5) PubTator annotation timeouts¶
Article annotation sections (annotations) require PubTator3 and can be slower than base PubMed retrieval.
When this section is slow or fails, verify basic article lookup first.
If base lookup succeeds but annotations fail repeatedly, retry later and keep the workflow moving with base metadata.
6) AlphaGenome prediction connection issues¶
get variant <id> predict uses AlphaGenome over gRPC and requires an API key.
Missing key or TLS/connectivity issues are the two most common failure paths.
Checklist:
- Confirm
ALPHAGENOME_API_KEYis set - Validate outbound access to
gdmscience.googleapis.com - Retry with a known-good variant
7) NCI CTS API authentication failures¶
Trial searches with --source nci require NCI_API_KEY.
If this key is missing, BioMCP returns an explicit ApiKeyRequired error.
8) OncoKB enrichment appears limited¶
Without ONCOKB_TOKEN, BioMCP uses the OncoKB demo endpoint with reduced capability.
Set a production token for full enrichment behavior.
9) Date validation errors¶
Invalid dates are rejected before API calls. Use ISO format YYYY-MM-DD and valid calendar dates.
Examples that should fail immediately:
biomcp search article -g BRAF --since 2024-13-01 --limit 1
biomcp search article -g BRAF --since 2024-02-30 --limit 1
10) Install/update ownership conflicts¶
If biomcp update cannot replace the current binary (e.g. permission issues),
re-run the installer:
11) Local build missing protoc¶
The project includes gRPC clients and requires protoc to build from source.
- macOS:
brew install protobuf - Ubuntu/Debian:
apt-get install protobuf-compiler
12) Still blocked¶
Capture one failing command with full stderr and include:
- BioMCP version (
biomcp version) - Command and flags
- Whether
--no-cachechanges behavior - Source-specific API key state (set or unset)