# 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.

For a successful JSON or MCP response that includes optional source-backed
sections, inspect `section_outcomes` first. `empty` means a contacted source
completed successfully with no evidence;
`unavailable` means no usable result was obtained; and `degraded` preserves
partial evidence. `_meta.section_sources` is the matching provenance projection
and credits only successful providers. Enable `RUST_LOG=warn` only after checking
these in-band fields.

Markdown places a safe, copyable `Retry:` command directly after each
recoverable degraded or unavailable section. The same recovery commands lead
JSON `_meta.next_commands`; each retries only the affected canonical section
when the CLI exposes one. Successful article searches use source-specific
retries only when that source accepts the current filters.

For a hard remote-source failure, JSON may include `error.source` and
`error.recovery`; human errors name the same canonical source and action. Retry
a transient source, review source configuration when instructed, or narrow the
request when the response exceeded BioMCP's body limit. Source fields are
omitted for unwrapped transport errors when provider identity is unavailable;
legacy source-shaped errors with an unknown name use `BioMCP source`. Public
diagnostics intentionally do not echo request URLs, credentials, provider
response bodies, parser detail,
or local paths, so use the canonical source label rather than expecting raw
transport detail.

## 1) Validate connectivity first

Run API-level checks before debugging entity-specific commands:

```bash
biomcp health --apis-only
```

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:

```bash
biomcp --no-cache search gene -q BRAF --limit 3
biomcp --no-cache get variant rs113488022
```

This mode makes no managed HTTP-cache or article-session reads or writes.
Article `--session` is therefore incompatible with it. Explicit downloads and
provider-side request logs are outside that promise.

If `--no-cache` works while cached mode fails repeatedly, `biomcp cache clean`
is the safe first step before any manual wipe. If you override the cache root
with `BIOMCP_CACHE_DIR` or `cache.toml`, run `biomcp cache path` first to print
the managed HTTP cache path under the resolved cache root.

```bash
biomcp cache clean
biomcp cache clean --dry-run
biomcp cache clean --max-age 7d
```

If targeted cleanup still does not recover the cache, use
`biomcp cache clear --yes` for a full wipe of the managed `http/` and ten-minute
article-session trees tied to
the resolved cache root you printed with `biomcp cache path`. `cache clear`
never touches the sibling `downloads/` directory, so the choice is explicit:
start with `cache clean` for targeted GC, escalate to `cache clear --yes` only
when you need the destructive full wipe.

If a cache command reports that it cannot secure managed local state, inspect
the configured root for symlinks, hard links, unsupported file types, or an ACL
that the current account cannot change. BioMCP fails before reading or writing
provider responses or article queries; do not bypass this check by making the
directory world-readable.

## 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 ctgov` or `--source nci` to isolate source behavior.
- Avoid changing both geographic and ESSIE filters in the same troubleshooting step.

Examples:

```bash
biomcp search trial -c melanoma --source ctgov --limit 5
biomcp search trial -c melanoma --source nci --limit 5
```

## 4) OpenFDA FAERS / CDC WONDER VAERS / recall limits

OpenFDA-backed adverse-event, recall, and device searches are currently capped
by BioMCP at `--limit <= 50` per request. CDC WONDER VAERS is a separate
aggregate-only path: use plain vaccine query text, avoid FAERS-only filters on
that route, and use `biomcp health --apis-only` if the VAERS row looks
unavailable.

```bash
biomcp search adverse-event --drug pembrolizumab --limit 50
biomcp search adverse-event "MMR vaccine" --source vaers --limit 10
biomcp search adverse-event --type recall --classification "Class I" --limit 50
```

If you use `--source all` with unsupported VAERS filters such as `--reaction`,
`--outcome`, `--serious`, date filters, age filters, `--suspect-only`,
`--sex`, `--reporter`, or `--count`, BioMCP should keep the FAERS result and
record the skipped VAERS status in JSON instead of failing the whole search.

If you have an OpenFDA API key, export it to increase quota stability:

```bash
export OPENFDA_API_KEY="..."
```

## 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.

```bash
biomcp get article 22663011
biomcp get article 22663011 annotations
```

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_KEY` is set
- Validate outbound access to `gdmscience.googleapis.com`
- Retry with a known-good variant

```bash
export ALPHAGENOME_API_KEY="..."
biomcp get variant "chr7:g.140453136A>T" predict
```

## 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.

```bash
export NCI_API_KEY="..."
biomcp search trial -c melanoma --source nci --limit 5
```

## 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.

```bash
export ONCOKB_TOKEN="..."
biomcp get variant "BRAF V600E"
```

## 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:

```bash
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

`biomcp update` fails closed when the release SHA256 checksum sidecar is missing
or invalid, before replacing the current binary. There is no unverified-install
override. Rerun the verified standalone installer if a release is incomplete.

Self-update and uninstall require the adjacent `biomcp.install.json` ownership
receipt. Package-manager installs must be upgraded or removed with that manager.
Windows self-update is unsupported; rerun the verified standalone installer:

```bash
curl -fsSL https://biomcp.org/install.sh | bash
```

## 11) AlphaGenome protobuf regeneration needs protoc

Normal builds do not run or require `protoc`; they consume the committed
AlphaGenome generated Rust source. Only maintainers changing the protobuf inputs
need pinned `protoc` 28.3. After installing that exact version, run
`scripts/regenerate-alphagenome-proto`; use
`scripts/regenerate-alphagenome-proto --check` to report drift without writing.

If `protoc --version` reports anything other than `libprotoc 28.3`, the
regeneration command fails before generating a candidate.

## 12) Still blocked

Capture one failing command with full stderr and include:

- BioMCP version (`biomcp version`)
- Command and flags
- Whether `--no-cache` changes behavior
- Source-specific API key state (set or unset)

## 13) EU drug data not available

EU drug regulatory, safety, and shortage sections depend on the local EMA
human-medicines JSON batch. BioMCP auto-downloads that data on first use for
`--region eu|all` drug workflows and for the default plain-name
U.S.+EU+WHO drug search, but full `biomcp health` is still the right
readiness view when you need to debug the local EMA state:

```bash
biomcp health
```

Interpret the EMA row like this:

- `configured`: `BIOMCP_EMA_DIR` is set and all required EMA JSON files are present
- `configured (stale)`: `BIOMCP_EMA_DIR` is set and the EMA batch is present, but older than the 72-hour refresh window
- `available (default path)`: BioMCP found a complete EMA batch in the default platform data directory
- `available (default path, stale)`: the default-path EMA batch is complete but older than the 72-hour refresh window
- `not configured`: no EMA batch was found at the default path, so EU drug features are currently unavailable but the install is not considered broken
- `error (missing: ...)`: BioMCP found a partial EMA batch; install the missing files or point `BIOMCP_EMA_DIR` at a complete batch

If a refresh fails, retry explicitly:

```bash
biomcp ema sync
```

If you need to override the default path:

```bash
export BIOMCP_EMA_DIR="/path/to/ema-human"
biomcp health
```

Manual preseed remains supported for offline or controlled environments. A
complete EMA root must contain:

- `medicines.json`
- `post_authorisation.json`
- `referrals.json`
- `psusas.json`
- `dhpcs.json`
- `shortages.json`

## 14) WHO drug data not available

WHO regional regulatory search/get flows depend on the local WHO
finished-pharmaceutical-products CSV, the active-pharmaceutical-ingredients
CSV, and the vaccine CSV. BioMCP auto-downloads all three exports on first use
for `--region who|all` drug workflows, explicit WHO vaccine search
(`--product-type vaccine`), and the default plain-name U.S.+EU+WHO drug search:

```bash
biomcp health
```

Interpret the WHO row like this:

- `configured`: `BIOMCP_WHO_DIR` is set and all three WHO exports are present
- `configured (stale)`: `BIOMCP_WHO_DIR` is set and complete, but at least one WHO export is older than the 72-hour refresh window
- `available (default path)`: BioMCP found all three WHO exports in the default platform data directory
- `available (default path, stale)`: the default-path WHO root is complete, but at least one export is older than the 72-hour refresh window
- `not configured`: no complete WHO root was found at the default path, so WHO regional drug features are currently unavailable but the install is not considered broken
- `error (missing: ...)`: BioMCP found a partial WHO root or unreadable file; install all three exports or point `BIOMCP_WHO_DIR` at a complete root

If a refresh fails, retry explicitly:

```bash
biomcp who sync
```

If you need to override the default path:

```bash
export BIOMCP_WHO_DIR="/path/to/who-pq"
biomcp health
```

Manual preseed remains supported for offline or controlled environments. A
complete WHO root must contain:

- `who_pq.csv`
- `who_api.csv`
- `who_vaccines.csv`

## 15) CDC CVX/MVX vaccine bridge data not available

Default plain-name vaccine searches that include the EU path and explicit
`search drug <brand> --region eu|all` vaccine searches can use the local CDC
CVX/MVX bundle after MyChem identity resolution misses. Explicit WHO vaccine
name/brand searches with `--region who --product-type vaccine` can use the same
bridge. Full `biomcp health` is the right readiness surface when you need to
debug the local CDC state:

```bash
biomcp health
```

Interpret the CDC row like this:

- `configured`: `BIOMCP_CVX_DIR` is set and all three CDC files are present
- `configured (stale)`: `BIOMCP_CVX_DIR` is set and complete, but at least one CDC file is older than the 30-day refresh window
- `available (default path)`: BioMCP found a complete CDC CVX/MVX bundle in the default platform data directory
- `available (default path, stale)`: the default-path CDC bundle is complete, but at least one file is older than the 30-day refresh window
- `not configured`: no complete CDC root was found at the default path, so the EMA/default/WHO vaccine-brand bridge is currently unavailable but the install is not considered broken
- `error (missing: ...)`: BioMCP found a partial CDC root or unreadable file; install the missing files or point `BIOMCP_CVX_DIR` at a complete bundle

If a refresh fails, retry explicitly:

```bash
biomcp cvx sync
```

If you need to override the default path:

```bash
export BIOMCP_CVX_DIR="/path/to/cvx"
biomcp health
```

Manual preseed remains supported for offline or controlled environments. A
complete CDC root must contain:

- `cvx.txt`
- `TRADENAME.txt`
- `mvx.txt`

The CDC bundle augments the EMA/default vaccine identity path plus explicit WHO
vaccine name/brand search when `--product-type vaccine` is set. It does not
change WHO finished-pharma/API lookups or `get drug`, and pure `--region us`
searches do not use the CVX root.

## 16) DDInter local data not available

`biomcp drug interactions <name>` and `get drug <name> interactions` depend on
an installed local DDInter CSV bundle. Normal reads do not download or refresh
it. Run `biomcp ddinter sync` explicitly
to install or replace all eight ATC-sliced files. Full `biomcp health` is the
readiness surface for debugging local DDInter state:

```bash
biomcp health
```

Interpret the DDInter row like this:

- `configured`: `BIOMCP_DDINTER_DIR` is set and all required DDInter CSV files are present
- `configured (stale)`: `BIOMCP_DDINTER_DIR` is set and complete, but at least one file is older than the 72-hour refresh window
- `available (default path)`: BioMCP found a complete DDInter bundle in the default platform data directory
- `available (default path, stale)`: the default-path DDInter bundle is complete but older than the 72-hour refresh window
- `not configured`: no complete DDInter root was found at the default path, so DDInter-backed interaction rows are currently unavailable but the install is not considered broken
- `error (missing: ...)`: BioMCP found a partial DDInter root or unreadable file; install the missing files or point `BIOMCP_DDINTER_DIR` at a complete bundle

If an explicit refresh fails, the prior complete bundle remains usable. Retry with:

```bash
biomcp ddinter sync
```

If you need to override the default path:

```bash
export BIOMCP_DDINTER_DIR="/path/to/ddinter"
biomcp health
```

Manual preseed remains supported for offline or controlled environments. A
complete DDInter root must contain the eight public DDInter CSV files downloaded
from the ATC-sliced DDInter bundle. Empty interaction results stay scoped to the
current DDInter bundle and do not prove absence of clinical interactions.

## 17) Diagnostic local data not available

Diagnostic search/get flows depend on two local bundles:

- the NCBI GTR bundle for gene-centric diagnostics
- the WHO IVD CSV for infectious-disease diagnostics

BioMCP auto-downloads both on first use, but full `biomcp health` is still the
right readiness surface when you need to debug the local diagnostic state:

```bash
biomcp health
```

Interpret the rows like this:

- `GTR local data (...)`: local GTR readiness for gene-capable diagnostic search/get
- `WHO IVD local data (...)`: local WHO infectious-disease diagnostic readiness
- `configured`: the corresponding env var is set and the required file set is present
- `configured (stale)`: the configured root is complete but older than the source-specific refresh window
- `available (default path)`: the default platform data directory contains a complete root
- `available (default path, stale)`: the default root is complete but stale
- `not configured`: no complete root exists yet at the default path
- `error (missing: ...)`: BioMCP found a partial root or unreadable file

If a refresh fails, retry explicitly:

```bash
biomcp gtr sync
biomcp who-ivd sync
```

If you need to override the default path:

```bash
export BIOMCP_GTR_DIR="/path/to/gtr"
export BIOMCP_WHO_IVD_DIR="/path/to/who-ivd"
biomcp health
```

Manual preseed remains supported for offline or controlled environments. A
complete GTR root must contain:

- `test_version.gz`
- `test_condition_gene.txt`

A complete WHO IVD root must contain:

- `who_ivd.csv`