<!--
# COPYRIGHT NOTICE
# This file is part of the "Universal Biomedical Skills" project.
# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
# All Rights Reserved.
#
# This code is proprietary and confidential.
# Unauthorized copying of this file, via any medium is strictly prohibited.
#
# Provenance: Authenticated by MD BABU MIA

-->

# Troubleshooting Guide

This guide helps you resolve common issues with BioMCP installation, configuration, and usage.

## Installation Issues

### Prerequisites Not Met

**macOS:**

```bash
# Install uv (recommended)
brew install uv

# Or using the official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Node.js for npx (if needed)
brew install node
```

**Linux:**

```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
```

**Windows:**

```powershell
# Install uv
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install Node.js from https://nodejs.org
```

### "Command not found" Error

After installing BioMCP, if you get "command not found":

1. **Restart your terminal** - PATH updates require a new session

2. **Check installation location:**

   ```bash
   # For uv tool install
   ls ~/.local/bin/biomcp

   # For pip install
   which biomcp
   ```

3. **Add to PATH manually:**

   ```bash
   # Add to ~/.bashrc or ~/.zshrc
   export PATH="$HOME/.local/bin:$PATH"
   ```

4. **Reinstall with force:**

   ```bash
   uv tool install biomcp --force
   ```

5. **Use full path:**
   ```bash
   ~/.local/bin/biomcp --version
   ```

### Python Version Issues

BioMCP requires Python 3.10 or higher:

```bash
# Check Python version
python --version

# If too old, install newer version
# macOS
brew install python@3.11

# Linux
sudo apt update
sudo apt install python3.11

# Use pyenv for version management
pyenv install 3.11.8
pyenv local 3.11.8
```

## Configuration Issues

### API Key Not Working

**Environment Variable Not Set:**

```bash
# Check if set
echo $NCI_API_KEY

# Set temporarily
export NCI_API_KEY="your-key-here"

# Set permanently in ~/.bashrc or ~/.zshrc
echo 'export NCI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc
```

**Wrong API Key Format:**

- NCI keys: Should be 36 characters (UUID format)
- AlphaGenome: Alphanumeric string
- cBioPortal: JWT token format

**API Key Permissions:**

```bash
# Test NCI API key
biomcp health check --verbose

# Test specific API
curl -H "X-API-KEY: $NCI_API_KEY" \
  "https://cts.nlm.nih.gov/api/v2/trials?size=1"
```

### SSL Certificate Errors

**Update certificates:**

```bash
# Python certificates
pip install --upgrade certifi

# System certificates (macOS)
brew install ca-certificates

# System certificates (Linux)
sudo apt-get update
sudo apt-get install ca-certificates
```

**Corporate proxy issues:**

```bash
# Set proxy environment variables
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1"

# Configure pip for proxy
pip config set global.proxy http://proxy.company.com:8080
```

## Search Issues

### No Results Found

**1. Check gene symbol:**

```bash
# Wrong: common names
biomcp article search --gene HER2  # ❌

# Correct: official HGNC symbol
biomcp article search --gene ERBB2  # ✅

# Find correct symbol
biomcp gene get HER2  # Will suggest ERBB2
```

**2. Too restrictive filters:**

```bash
# Too specific - may return nothing
biomcp article search --gene BRAF --disease "stage IV melanoma" \
  --chemical "dabrafenib and trametinib combination"

# Better - broader search
biomcp article search --gene BRAF --disease melanoma \
  --keyword "dabrafenib trametinib"
```

**3. Check data availability:**

```bash
# Test if gene exists in database
biomcp gene get YOUR_GENE

# Test if disease term is recognized
biomcp disease get "your disease term"
```

### Location Search Not Working

Location searches require coordinates:

```bash
# Wrong - city name only
biomcp trial search --condition cancer --city "New York"  # ❌

# Correct - with coordinates
biomcp trial search --condition cancer \
  --latitude 40.7128 --longitude -74.0060 --distance 50  # ✅
```

Common coordinates:

- New York: 40.7128, -74.0060
- Los Angeles: 34.0522, -118.2437
- Chicago: 41.8781, -87.6298
- Houston: 29.7604, -95.3698
- Boston: 42.3601, -71.0589

### Preprint Search Issues

**Preprints not appearing:**

```bash
# Check if preprints are being excluded
biomcp article search --gene BRAF --no-preprints  # Excludes preprints

# Include preprints (default)
biomcp article search --gene BRAF  # Includes preprints
```

**DOI not found:**

```bash
# Ensure correct DOI format
biomcp article get "10.1101/2024.01.20.23288905"  # bioRxiv format

# Not all preprints are indexed immediately
# Try searching by title/keywords instead
```

## Performance Issues

### Slow Searches

**1. Reduce result count:**

```bash
# Default may be too high
biomcp article search --gene TP53 --limit 100  # Slow

# Reduce for faster results
biomcp article search --gene TP53 --limit 10   # Fast
```

**2. Use specific filters:**

```bash
# Broad search - slow
biomcp trial search --condition cancer

# Specific search - faster
biomcp trial search --condition "melanoma" --phase PHASE3 \
  --status RECRUITING --country "United States"
```

**3. Check API health:**

```bash
# See which APIs are slow
biomcp health check --verbose

# Check specific API
biomcp health check --apis-only
```

### Timeout Errors

**Increase timeout for slow networks:**

```bash
# Set environment variable
export BIOMCP_TIMEOUT=300  # 5 minutes

# Or use configuration file
echo "timeout: 300" > ~/.biomcp/config.yml
```

**For specific operations:**

```python
# In Python scripts
import asyncio
asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
```

### Memory Issues

**Large result sets:**

```bash
# Process in batches
for i in {1..10}; do
  biomcp article search --gene BRCA1 --page $i --limit 100
done

# Use streaming where available
biomcp article search --gene TP53 --format jsonl | \
  while read line; do
    echo "$line" | jq '.pmid'
  done
```

## MCP Server Issues

### Testing Server Connectivity

**1. Test with MCP Inspector:**

```bash
npx @modelcontextprotocol/inspector uv run --with biomcp-python biomcp run
```

Open http://127.0.0.1:6274 and verify:

- Tools list loads
- Can invoke a simple tool like `gene_getter`

**2. Test with curl (HTTP mode):**

```bash
# Start server in HTTP mode
biomcp run --mode http --port 8000

# Test health endpoint
curl http://localhost:8000/health

# Test MCP endpoint
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'
```

### Claude Desktop Integration Issues

**Server not appearing:**

1. Check configuration file location:

   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. Validate JSON syntax:

   ```bash
   # macOS
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .
   ```

3. Check server starts correctly:
   ```bash
   # Test the exact command from config
   uv run --with biomcp-python biomcp run
   ```

**Server crashes:**
Check logs:

```bash
# Enable debug logging
export BIOMCP_LOG_LEVEL=DEBUG
uv run --with biomcp-python biomcp run
```

Common fixes:

- Update to latest version: `uv tool install biomcp --force`
- Clear cache: `rm -rf ~/.biomcp/cache`
- Check port conflicts: `lsof -i :8000`

## Data Quality Issues

### Outdated Results

**Check data freshness:**

```bash
# See when databases were last updated
biomcp health check --verbose | grep "Last updated"
```

**Clear cache if needed:**

```bash
# Remove cached results
rm -rf ~/.biomcp/cache

# Or set cache TTL
export BIOMCP_CACHE_TTL=900  # 15 minutes
```

### Missing Annotations

**PubTator3 annotations missing:**

- Some newer articles may not be fully annotated yet
- Try searching by PMID directly
- Check if article is indexed: search by title

**Variant annotations incomplete:**

- Not all variants have all annotation types
- Rare variants may lack population frequencies
- Novel variants won't have ClinVar data

## Error Messages

### Common Error Codes

**HTTP 429 - Rate Limit Exceeded:**

```bash
# Add delay between requests
biomcp article search --gene BRAF --delay 1000  # 1 second

# Or reduce parallel requests
export BIOMCP_MAX_CONCURRENT=2
```

**HTTP 404 - Not Found:**

- Check identifier format (PMID, NCT ID, etc.)
- Verify record exists in source database
- Try alternative identifiers

**HTTP 500 - Server Error:**

- External API may be down
- Check status: `biomcp health check`
- Try again later

### Debugging

**Enable verbose logging:**

```bash
# Set log level
export BIOMCP_LOG_LEVEL=DEBUG

# Run with verbose output
biomcp article search --gene BRAF --verbose

# Check log files
tail -f ~/.biomcp/logs/biomcp.log
```

**Report bugs:**
Include when reporting issues:

1. BioMCP version: `biomcp --version`
2. Full error message and stack trace
3. Command that caused the error
4. Operating system and Python version
5. Relevant environment variables

Report at: https://github.com/genomoncology/biomcp/issues

## Getting Help

### Quick Checks

1. **Check FAQ first**: [Frequently Asked Questions](faq-condensed.md)
2. **Search existing issues**: [GitHub Issues](https://github.com/genomoncology/biomcp/issues)
3. **Check examples**: [How-to Guides](how-to-guides/01-find-articles-and-cbioportal-data.md)

### Community Support

- Issue Tracker: Report bugs, request features
- Documentation: PRs welcome for improvements

### Professional Support

For commercial support, contact: support@genomoncology.com

---

_Still having issues? [Open a GitHub issue](https://github.com/genomoncology/biomcp/issues/new) with details._


<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->