Common Issues and Solutions

This guide covers the most frequently encountered issues when working with SpoonOS and their solutions.

Installation Issues

Python Version Compatibility

Problem: ImportError or ModuleNotFoundError when importing SpoonOS modules

Symptoms:

ImportError: No module named 'spoon_ai'
ModuleNotFoundError: No module named 'asyncio'

Solution:

1. Ensure Python 3.10+ is installed:

   python --version
   # Should show Python 3.10.0 or higher

2. Create a new virtual environment:

   python -m venv spoon-env
   source spoon-env/bin/activate  # Linux/macOS
   # or
   spoon-env\\Scripts\\activate     # Windows

3. Install dependencies:

   pip install -r requirements.txt

Dependency Conflicts

Problem: Package version conflicts during installation

Symptoms:

ERROR: pip's dependency resolver does not currently have a solution
Conflicting dependencies: package-a requires package-b>=2.0, but package-c requires package-b<2.0

Solution:

1. Use a fresh virtual environment
2. Install packages one by one to identify conflicts
3. Check requirements.txt for version pinning issues
4. Use pip install --upgrade for outdated packages

Configuration Issues

API Key Problems

Problem: Authentication errors with LLM providers

Symptoms:

AuthenticationError: Invalid API key
Unauthorized: API key not found

Solution:

1. Verify API keys are set correctly:

   echo $OPENAI_API_KEY
   echo $ANTHROPIC_API_KEY

2. Check .env file format:

   # Correct format
   OPENAI_API_KEY=sk-your-actual-key-here
   
   # Incorrect (no quotes needed)
   OPENAI_API_KEY="sk-your-actual-key-here"

3. Validate API key format:

   • OpenAI: Starts with sk-
   • Anthropic: Starts with sk-ant-
   • Google: 39-character string

4. Test API key validity:

   curl -H "Authorization: Bearer $OPENAI_API_KEY" \\
        https://api.openai.com/v1/models

Configuration File Errors

Problem: JSON parsing errors in config.json

Symptoms:

JSONDecodeError: Expecting ',' delimiter
ConfigurationError: Invalid configuration format

Solution:

1. Validate JSON syntax using online validator or:

   python -m json.tool config.json

2. Common JSON errors:

   // Wrong: trailing comma
   {
     "key": "value",
   }
   
   // Correct
   {
     "key": "value"
   }

3. Use CLI validation:

   python main.py
   > validate-config

Agent Issues

Agent Loading Failures

Problem: Agent fails to load or initialize

Symptoms:

AgentError: Agent 'my_agent' not found
ImportError: cannot import name 'MyAgent'

Solution:

1. Check agent configuration in config.json:

   {
     "agents": {
       "my_agent": {
         "class": "SpoonReactAI",
         "description": "My custom agent"
       }
     }
   }

2. Verify agent class exists:

   from spoon_ai.agents import SpoonReactAI
   # Should not raise ImportError

3. Check for typos in agent names and class names

4. List available agents:

   python main.py
   > list-agents

Tool Loading Issues

Problem: Tools not available or failing to load

Symptoms:

ToolError: Tool 'crypto_tool' not found
ModuleNotFoundError: No module named 'spoon_toolkits'

Solution:

1. Install spoon-toolkit package:

   pip install -e spoon-toolkit/

2. Check tool configuration:

   {
     "tools": [
       {
         "name": "crypto_tool",
         "type": "builtin",
         "enabled": true
       }
     ]
   }

3. Verify environment variables for tools:

   echo $OKX_API_KEY
   echo $COINGECKO_API_KEY

4. List available tools:

   python main.py
   > list-toolkit-categories
   > list-toolkit-tools crypto

LLM Provider Issues

Provider Connection Failures

Problem: Cannot connect to LLM providers

Symptoms:

ConnectionError: Failed to connect to OpenAI API
TimeoutError: Request timed out

Solution:

1. Check internet connectivity:

   ping api.openai.com
   ping api.anthropic.com

2. Verify API endpoints are accessible:

   curl -I https://api.openai.com/v1/models

3. Check firewall and proxy settings

4. Test with different provider:

   python main.py
   > llm-status

Rate Limiting

Problem: API rate limits exceeded

Symptoms:

RateLimitError: Rate limit exceeded
HTTPError: 429 Too Many Requests

Solution:

1. Implement exponential backoff in configuration:

   {
     "llm": {
       "retry_attempts": 3,
       "retry_delay": 1.0,
       "exponential_backoff": true
     }
   }

2. Use multiple API keys for load balancing

3. Reduce request frequency

4. Upgrade to higher tier API plan

MCP (Model Context Protocol) Issues

MCP Server Connection Problems

Problem: Cannot connect to MCP servers

Symptoms:

MCPError: Failed to connect to MCP server
ConnectionRefusedError: [Errno 111] Connection refused

Solution:

1. Verify MCP server is running:

   curl http://localhost:8765/health

2. Check MCP server configuration:

   {
     "mcp_servers": [
       {
         "name": "my_server",
         "url": "http://localhost:8765",
         "transport": "sse"
       }
     ]
   }

3. Start MCP server:

   python mcp_server.py

4. Check server logs for errors

MCP Tool Discovery Issues

Problem: MCP tools not discovered or available

Symptoms:

MCPError: No tools found on server
ToolError: MCP tool 'my_tool' not available

Solution:

1. Verify tools are registered on MCP server:

   @mcp.tool()
   def my_tool():
       return "Hello from MCP"

2. Check MCP server tool listing:

   curl http://localhost:8765/tools

3. Restart MCP server after adding tools

4. Verify tool permissions and authentication

Performance Issues

Slow Response Times

Problem: Agent responses are very slow

Symptoms:

• Long delays before responses
• Timeout errors
• High CPU/memory usage

Solution:

1. Check system resources:

   python main.py
   > system-info

2. Optimize LLM configuration:

   {
     "llm": {
       "temperature": 0.7,
       "max_tokens": 1000,
       "timeout": 30
     }
   }

3. Enable caching:

   {
     "cache": {
       "enabled": true,
       "ttl": 3600
     }
   }

4. Reduce tool complexity and number of tools

Memory Issues

Problem: High memory usage or out-of-memory errors

Symptoms:

MemoryError: Unable to allocate memory
Process killed (OOM)

Solution:

1. Monitor memory usage:

   python main.py
   > system-info

2. Reduce conversation history:

   python main.py
   > new-chat

3. Optimize agent configuration:

   {
     "config": {
       "max_steps": 5,
       "max_tokens": 500
     }
   }

4. Use lighter LLM models (e.g., GPT-3.5 instead of GPT-4)

Blockchain Integration Issues

RPC Connection Problems

Problem: Cannot connect to blockchain RPC endpoints

Symptoms:

ConnectionError: Failed to connect to RPC
HTTPError: 403 Forbidden

Solution:

1. Verify RPC URL is correct:

   curl -X POST -H "Content-Type: application/json" \\
        --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \\
        $RPC_URL

2. Check RPC provider limits and authentication

3. Try alternative RPC endpoints:

   # Ethereum
   export RPC_URL="https://eth.llamarpc.com"
   export RPC_URL="https://rpc.ankr.com/eth"

4. Verify network connectivity and firewall settings

Transaction Failures

Problem: Blockchain transactions fail or revert

Symptoms:

TransactionError: Transaction reverted
InsufficientFundsError: Not enough balance

Solution:

1. Check wallet balance:

   python main.py
   > token-by-symbol ETH

2. Verify gas settings:

   {
     "blockchain": {
       "gas_limit": 21000,
       "gas_price": "20000000000"
     }
   }

3. Check transaction parameters and recipient address

4. Verify private key and wallet configuration

Debugging Techniques

Enable Debug Logging

# Set environment variables
export DEBUG=true
export LOG_LEVEL=debug

# Run with verbose output
python main.py

Use System Diagnostics

python main.py
> system-info
> llm-status
> validate-config

Check Configuration

# Validate configuration
python main.py
> validate-config

# Check migration status
python main.py
> check-config

Test Individual Components

# Test LLM connection
from spoon_ai.llm import LLMManager
llm = LLMManager()
response = await llm.generate("Hello, world!")

# Test tool execution
from spoon_toolkits.crypto import GetTokenPriceTool
tool = GetTokenPriceTool()
result = await tool.execute(symbol="BTC")

Getting Help

Documentation Resources

• Installation Guide
• Configuration Guide
• API Reference
• How-To Guides

📚 Working Examples

🎯 Comprehensive Graph Demo

GitHub: View Source

Perfect for troubleshooting:

• Graph system setup and configuration
• Memory management and state persistence issues
• Parallel execution and routing problems
• Production deployment patterns

🔍 MCP Spoon Search Agent

GitHub: View Source

Great for debugging:

• MCP server connection and integration issues
• Tool discovery and loading problems
• API rate limiting and error handling
• Multi-tool orchestration challenges

📊 Graph Crypto Analysis

GitHub: View Source

Excellent for testing:

• Real API integration and authentication
• Data processing and validation issues
• Performance optimization problems
• Complex workflow debugging

Community Support

• GitHub Issues: Report bugs and feature requests
• Discord: Real-time community support
• Documentation: Comprehensive guides and working examples

Diagnostic Information

When reporting issues, include:

• Python version (python --version)
• SpoonOS version
• Operating system
• Error messages and stack traces
• Configuration files (sanitized)
• Steps to reproduce

Log Collection

# Enable debug logging
export DEBUG=true
export LOG_LEVEL=debug

# Capture logs
python main.py 2>&1 | tee spoon_debug.log

# Include relevant log sections in issue reports

Prevention Tips

Regular Maintenance

• Keep dependencies updated
• Rotate API keys regularly
• Monitor system resources
• Backup configuration files
• Test in development environment first

Best Practices

• Use version control for configurations
• Implement proper error handling
• Monitor API usage and costs
• Set up alerts for critical issues
• Document custom configurations

Environment Management

• Use separate environments for development/production
• Pin dependency versions in requirements.txt
• Use environment variables for sensitive data
• Regularly test backup and recovery procedures

See Also

• Debugging Guide
• Performance Optimization
• System Requirements"}

Prevention Tips

Regular Maintenance

• Keep dependencies updated
• Rotate API keys regularly
• Monitor system resources
• Backup configuration files
• Test in development environment first

Best Practices

• Use version control for configurations
• Implement proper error handling
• Monitor API usage and costs
• Set up alerts for critical issues
• Document custom configurations

Environment Management

• Use separate environments for development/production
• Pin dependency versions in requirements.txt
• Use environment variables for sensitive data
• Regularly test backup and recovery procedures

See Also

• Debugging Guide
• Performance Optimization
• System Requirements"}