docs/getting-started/troubleshooting.md

Troubleshooting Guide

Common issues and their solutions.

Installation Issues

uv not found

Symptom: command not found: uv

Solution:

# Install uv
pip install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh

Python version mismatch

Symptom: Python 3.11+ required or syntax errors

Solution:

# Check version
python --version

# Install Python 3.11+ via pyenv
pyenv install 3.11
pyenv local 3.11

Dependency conflicts

Symptom: Package version conflicts during install

Solution:

# Clean install
rm -rf .venv uv.lock
uv sync --all-extras

Runtime Issues

Slow first query

Symptom: First query takes 30+ seconds

Cause: Model loading (sentence-transformers) on first use

Solution: This is expected. Subsequent queries are faster.

Rate limit errors

Symptom: RateLimitError or 429 HTTP status

Cause: Too many requests to external APIs

Solutions:

1. Add NCBI API key for PubMed:

   NCBI_API_KEY=your-key-here
   

2. Wait and retry (rate limits reset)
3. Reduce MAX_ITERATIONS

No search results

Symptom: Empty results from searches

Possible causes:

• Network issues
• External API downtime
• Query too specific

Solutions:

1. Check internet connection
2. Try a broader query
3. Check API status:
   • PubMed Status
   • ClinicalTrials.gov

HuggingFace 500/401 errors

Symptom: Internal server errors or auth errors from HuggingFace

Cause: Large models (70B+) are routed to unreliable third-party providers

Solution: Use default model (Qwen 2.5 7B) which stays on HuggingFace native infrastructure. See CLAUDE.md for details.

OpenAI API errors

Symptom: Authentication errors with OpenAI

Solutions:

1. Verify key is valid: https://platform.openai.com/api-keys
2. Check for typos in .env
3. Ensure no trailing whitespace
4. Check quota: https://platform.openai.com/usage

Import errors

Symptom: ModuleNotFoundError when running

Solution:

# Always use uv run
uv run python src/app.py

# Not this
python src/app.py  # Won't find dependencies

ChromaDB errors

Symptom: Embedding or vector store errors

Solutions:

# Clear the database
rm -rf ./chroma_db

# Verify path is writable
ls -la ./

Development Issues

Pre-commit hook failures

Symptom: Commits rejected by pre-commit

Solution:

# Auto-fix formatting
make format

# Check manually
make lint
make typecheck

Type checking errors

Symptom: mypy errors on valid code

Solutions:

# Update stubs
uv add --dev types-package-name

# Or add ignore comment (last resort)
# type: ignore[error-code]

Test failures

Symptom: Tests pass locally but fail in CI

Possible causes:

• Environment differences
• Async timing issues
• Missing test data

Solutions:

# Run exactly like CI
make check

# Run specific test with verbose output
uv run pytest tests/unit/path/test_file.py -v -s

UI Issues

Gradio not starting

Symptom: Application exits immediately or port conflict

Solutions:

# Check if port is in use
lsof -i :7860

# Kill existing process
kill -9 $(lsof -t -i :7860)

# Or use different port
uv run python -c "import gradio; print(gradio.__version__)"

MCP tools not appearing

Symptom: Claude Desktop doesn't show DeepBoner tools

Solutions:

1. Verify URL: http://localhost:7860/gradio_api/mcp/
2. Check Claude Desktop config syntax
3. Restart Claude Desktop after config change
4. Ensure DeepBoner is running

Deployment Issues

Docker build fails

Symptom: Dockerfile build errors

Solutions:

# Clean build
docker build --no-cache -t deepboner .

# Check disk space
docker system df
docker system prune

Container exits immediately

Symptom: Container starts and stops

Solution:

# Check logs
docker logs <container_id>

# Run interactively
docker run -it deepboner bash

HuggingFace Spaces issues

Symptom: Space fails to build or run

Solutions:

1. Check Spaces logs in HuggingFace UI
2. Verify requirements.txt matches pyproject.toml
3. Check secrets are set correctly

Getting More Help

Enable debug logging

LOG_LEVEL=DEBUG uv run python src/app.py

Check system info

uv run python -c "
import sys
print(f'Python: {sys.version}')

import src
print(f'DeepBoner loaded')

from src.utils.config import settings
print(f'OpenAI key: {bool(settings.openai_api_key)}')
print(f'HF key: {bool(settings.hf_token)}')
"

Report an issue

If you can't resolve the issue:

1. Search existing issues: https://github.com/The-Obstacle-Is-The-Way/DeepBoner/issues
2. Create a new issue with:
   • Steps to reproduce
   • Expected vs actual behavior
   • Environment info (Python version, OS)
   • Relevant logs (redact API keys)

Related Documentation

• Installation Guide
• Configuration Guide
• SECURITY.md