Troubleshooting Tutorial¶

This Tutorial helps you diagnose and resolve common issues with ToolUniverse.

Quick Diagnostic¶

Run this diagnostic script to check your ToolUniverse installation:

from tooluniverse import ToolUniverse

# Run basic system check
try:
    tu = ToolUniverse()
    tu.load_tools()
    print(f"✅ ToolUniverse working correctly! {len(tu.all_tools)} tools loaded.")
except Exception as e:
    print(f"❌ Issue detected: {e}")

Most common installation problems and solutions.

Installation Issues¶

ImportError: No module named ‘tooluniverse’¶

Symptom: Python can’t find the ToolUniverse module.

Diagnosis:

python -c "import tooluniverse; print(tooluniverse.__version__)"

Solutions:

pip install tooluniverse

git clone https://github.com/zitniklab/tooluniverse
cd tooluniverse
pip install -e .

python -m venv tooluniverse_env
source tooluniverse_env/bin/activate  # Linux/Mac
# tooluniverse_env\Scripts\activate  # Windows
pip install tooluniverse

Dependency conflicts¶

Symptom: Conflicting package versions during installation.

Check dependencies:

pip check

Solutions:

Create clean environment:

conda create -n tooluniverse python=3.10
conda activate tooluniverse
pip install tooluniverse

Update conflicting packages:

pip install --upgrade requests urllib3 certifi

Install specific versions:
```
pip install 'requests>=2.25.0,<3.0.0'
```

Runtime Errors¶

Tool not found errors¶

Symptom: ToolNotFoundError: Tool 'XYZ' not found

Diagnosis:

from tooluniverse import ToolUniverse

tu = ToolUniverse()
tu.load_tools()

# List available tools
print("Available tools:")
for tool_name in tu.list_tools():
    print(f"  - {tool_name}")

Solutions:

Check tool name spelling:

# Correct tool names
correct_names = [
    "OpenTargets_get_associated_targets_by_disease_efoId",
    "PubChem_get_compound_info",
    "UniProt_get_protein_info"
]

Verify tool is loaded:

if "OpenTargets_tool" not in tu.list_tools():
    print("OpenTargets tool not loaded")
    # Check for missing dependencies

Manual tool loading:

from tooluniverse.opentargets_tool import OpenTargetsTool
tool = OpenTargetsTool()
tu.register_tool(tool)

API Authentication errors¶

Symptom: 401 Unauthorized or 403 Forbidden errors.

Diagnosis:

import os

# Check if API keys are set
api_keys = {
    'OPENTARGETS_API_KEY': os.getenv('OPENTARGETS_API_KEY'),
    'NCBI_API_KEY': os.getenv('NCBI_API_KEY'),
    'CHEMBL_API_KEY': os.getenv('CHEMBL_API_KEY')
}

for key, value in api_keys.items():
    status = "✓ Set" if value else "✗ Missing"
    print(f"{key}: {status}")

Solutions:

Set API keys:

export OPENTARGETS_API_KEY="your_key_here"
export NCBI_API_KEY="your_ncbi_key"

In Python:

import os
os.environ['OPENTARGETS_API_KEY'] = 'your_key_here'

Use .env file:

# Create .env file
echo "OPENTARGETS_API_KEY=your_key" >> .env
echo "NCBI_API_KEY=your_ncbi_key" >> .env

from dotenv import load_dotenv
load_dotenv()

Rate limiting errors¶

Symptom: 429 Too Many Requests or RateLimitExceeded

Diagnosis:

# Check rate limit status
from tooluniverse.utils import check_rate_limits

status = check_rate_limits()
print(f"Rate limit status: {status}")

Solutions:

Add delays between requests:

import time

for query in queries:
     result = tu.run(query)
     time.sleep(1)  # Wait 1 second between requests

Use batch processing:

# Process in smaller batches
batch_size = 5
for i in range(0, len(queries), batch_size):
     batch = queries[i:i+batch_size]
     results = tu.run_batch(batch)
     time.sleep(2)  # Pause between batches

Get API keys for higher limits:

Most services offer higher rate limits with API keys.

Network & Connectivity¶

Connection timeouts¶

Symptom: ConnectionTimeout or ReadTimeout errors.

Diagnosis:

import requests

# Test basic connectivity
try:
    response = requests.get('https://httpbin.org/delay/1', timeout=5)
    print(f"Network OK: {response.status_code}")
except requests.exceptions.Timeout:
    print("Network timeout - check connection")

Solutions:

Increase timeout:

tu = ToolUniverse(timeout=30)  # 30 second timeout

Check network connection:

ping google.com
curl -I https://platform-api.opentargets.org

Configure proxy (if needed):

import os
os.environ['HTTP_PROXY'] = 'http://proxy.company.com:8080'
os.environ['HTTPS_PROXY'] = 'http://proxy.company.com:8080'

SSL Certificate errors¶

Symptom: SSLError or certificate verification failures.

Solutions:

Update certificates:

pip install --upgrade certifi requests urllib3

Temporary bypass (not recommended for production):

import ssl
ssl._create_default_https_context = ssl._create_unverified_context

Corporate firewall:

Contact your IT department for proper certificate configuration.

Performance Issues¶

Slow query performance¶

Diagnosis:

import time
from tooluniverse import ToolUniverse

tu = ToolUniverse()

# Time a query
start_time = time.time()
result = tu.run({"name": "tool_name", "arguments": {}})
elapsed = time.time() - start_time

print(f"Query took {elapsed:.2f} seconds")

Optimization strategies:

Enable caching:

tu = ToolUniverse(enable_cache=True, cache_ttl=3600)

Use async operations:

import asyncio

async def run_queries():
     tasks = [tu.run_async(query) for query in queries]
     results = await asyncio.gather(*tasks)
     return results

Batch similar queries:

# Instead of individual queries
gene_info = []
for gene in genes:
     info = tu.run({
         "name": "UniProt_get_protein_info",
         "arguments": {"gene_symbol": gene}
     })
     gene_info.append(info)

# Use batch processing
queries = [
     {"name": "UniProt_get_protein_info", "arguments": {"gene_symbol": gene}}
     for gene in genes
]
results = tu.run_batch(queries)

Memory usage issues¶

Symptom: High memory consumption or MemoryError.

Diagnosis:

import psutil
import os

process = psutil.Process(os.getpid())
memory_mb = process.memory_info().rss / 1024 / 1024
print(f"Memory usage: {memory_mb:.1f} MB")

Solutions:

Process data in chunks:

def process_large_dataset(data, chunk_size=100):
     for i in range(0, len(data), chunk_size):
         chunk = data[i:i+chunk_size]
         yield tu.run_batch(chunk)

Clear cache periodically:
```
tu.clear_cache()
```

Use generators for large results:

def yield_results(queries):
     for query in queries:
         yield tu.run(query)

MCP Server Issues¶

MCP server won’t start¶

Symptom: Server fails to start or crashes immediately.

Diagnosis:

# Test server directly
python -m tooluniverse.smcp_server --debug

Solutions:

Check port availability:

# Check if port is in use
lsof -i :3000  # Linux/Mac
netstat -an | findstr :3000  # Windows

Use different port:

python -m tooluniverse.smcp_server --port 3001

Check permissions:

# Ensure user can bind to port
sudo python -m tooluniverse.smcp_server  # If needed

Claude/AI assistant not finding tools¶

Diagnosis:

Verify MCP server is running:
```
curl http://localhost:3000/health
```
Check Claude configuration:

Ensure MCP server is properly configured in Claude Desktop settings.

Solutions:

Restart both server and Claude
Check Claude logs for connection errors

Verify tool registration:

# In MCP server
tools = tu.list_tools()
print(f"Registered {len(tools)} tools")

Advanced Debugging¶

Enable debug logging¶

import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('tooluniverse')
logger.setLevel(logging.DEBUG)

# Now run your code
tu = ToolUniverse()

Capture detailed error information¶

import traceback

try:
    result = tu.run(query)
except Exception as e:
    print(f"Error: {e}")
    print(f"Type: {type(e).__name__}")
    print("Traceback:")
    traceback.print_exc()

Profile performance bottlenecks¶

import cProfile
import pstats

# Profile your code
profiler = cProfile.Profile()
profiler.enable()

# Your ToolUniverse code here
tu = ToolUniverse()
result = tu.run(query)

profiler.disable()

# Analyze results
stats = pstats.Stats(profiler)
stats.sort_stats('cumulative')
stats.print_stats(10)

Getting Help¶

If none of these solutions work:

Check the FAQ: FAQ - Frequently Asked Questions
Search GitHub issues: Issues
Create a bug report with:
- ToolUniverse version: tooluniverse.__version__
- Python version: python --version
- Operating system
- Full error message and traceback
- Minimal code example that reproduces the issue
Join our community: Discord server link

from tooluniverse.diagnostics import run_diagnostic
print(run_diagnostic())
Include this output in your bug report.