Skip to content

Error Codes

BioMCP exposes structured internal error variants through human-readable CLI messages. This reference maps each BioMcpError variant to likely causes and practical recovery steps.

Process exit codes

BioMCP uses process exit codes to distinguish parser failures from command execution failures:

  • exit 2: clap rejected the command before BioMCP command execution started. Example: biomcp search pathway --badflag
  • exit 1: the command parsed, then BioMCP returned BioMcpError::InvalidArgument for invalid or inconsistent usage. Examples: biomcp search pathway, biomcp get pathway hsa05200 events
  • exit 1: alias fallback guidance for get gene / get drug still counts as a not-found miss even when BioMCP can suggest a canonical retry command. Example: biomcp get gene ERBB1

Error catalog

Error variant Meaning Recovery guidance
HttpClientInit HTTP client could not initialize Check TLS/network stack, proxy settings, and local certificate configuration
Http HTTP request failed before receiving a successful response Retry the command and verify network connectivity
HttpMiddleware Retry/cache middleware failed Retry; if persistent, clear cache and re-run with --no-cache
Api Upstream API returned an error response Check API status, input values, and any source-specific constraints
ApiJson API response shape changed or returned malformed JSON Retry once; if repeatable, report issue because upstream format may have changed
NotFound Requested entity ID was not found Verify identifier format; run search before get when unsure
InvalidArgument Command arguments are invalid or inconsistent Re-run with --help and correct flag values/section names
ApiKeyRequired Source requires an API key that is not set Export the listed environment variable and retry
SourceUnavailable Requested source could not be used Switch sources if possible or retry later
Template Markdown/templating render failed Report issue (rendering bug)
Json Local JSON serialization/deserialization failed Retry; if persistent, report issue with command and payload context
Io File system I/O failed Check permissions, available disk space, and install/cache paths

Key environment variables

Variable Used by
ALPHAGENOME_API_KEY Variant predict section
DISGENET_API_KEY Scored DisGeNET sections on get gene and get disease
NCBI_API_KEY Higher-throughput PubTator, PMC OA, and NCBI ID converter requests
S2_API_KEY Optional authenticated Semantic Scholar requests for article search/get/helpers
NCI_API_KEY Trial source --source nci
ONCOKB_TOKEN Production OncoKB enrichment
OPENFDA_API_KEY Optional OpenFDA quota stability
UMLS_API_KEY Optional discover clinical crosswalk enrichment

Not-found troubleshooting pattern

When you get a NotFound error, validate in this order:

  1. Identifier syntax (rs..., NCT..., PMID, MONDO:...)
  2. Search by keyword or symbol
  3. Retry with a broader query
  4. If BioMCP prints Did you mean: ..., re-run the suggested canonical get command. In JSON mode, the same guidance is printed to stdout under _meta.alias_resolution and _meta.next_commands while the process still exits 1.

Examples:

biomcp search gene -q BRAF --limit 5
biomcp search trial -c melanoma --limit 5
biomcp search disease -q melanoma --limit 5