Troubleshooting Guide

This guide helps you solve common issues with QuantaLogic. Follow our systematic approach to identify and fix problems quickly.

Diagnostic Process

1. Identify the Issue
2. What were you trying to do?
3. What happened instead?

4. Any error messages?

5. Check Prerequisites

6. Python version
7. Required packages
8. API keys

9. Docker status (if using code tools)

10. Review Logs

11. Enable detailed logging
12. Check event monitoring
13. Analyze error patterns

Common Issues

Installation Problems

Python Version Mismatch

Error: Python 3.12 or later is required

Solution: 1. Check your Python version:

python --version

2. Install/upgrade Python:

# macOS
brew install python@3.12

# Linux
sudo apt update
sudo apt install python3.12

# Windows
# Download from python.org

Package Conflicts

Error: Dependency conflicts detected

Solution: 1. Create a fresh virtual environment:

python -m venv .venv
source .venv/bin/activate

2. Install with clean dependencies:

pip install --no-cache-dir quantalogic

API Key Issues

Missing API Key

ValueError: DEEPSEEK_API_KEY environment variable is not set

Solution: 1. Set the API key:

export DEEPSEEK_API_KEY="your-api-key"

2. Verify it's set:

echo $DEEPSEEK_API_KEY

Invalid API Key

Error: Authentication failed

Solution: 1. Check key validity in provider dashboard 2. Ensure no whitespace in key 3. Try regenerating the key

Docker Issues

Permission Denied

Error: permission denied while trying to connect to the Docker daemon socket

Solution: 1. Add user to docker group:

sudo usermod -aG docker $USER

2. Log out and back in 3. Verify:

docker ps

Container Errors

Error: container failed to start

Solution: 1. Check Docker status:

docker info

2. Clean up Docker:

docker system prune

3. Verify disk space:

df -h

Memory Issues

Memory Full

Error: memory_full event triggered

Solution: 1. Enable memory monitoring:

agent.event_emitter.on(
    ["memory_full", "memory_compacted"],
    console_print_events
)

2. Adjust memory settings:

agent = Agent(
    model_name="deepseek/deepseek-chat",
    memory_limit="2G"
)

Performance Degradation

Warning: Task execution time exceeding normal limits

Solution: 1. Monitor memory usage 2. Implement batch processing 3. Use memory optimization:

agent.compact_memory()

Tool Execution Issues

Tool Not Found

Error: Tool 'XYZ' not found

Solution: 1. Verify tool installation:

print(agent.available_tools)

2. Install missing tools:

from quantalogic.tools import RequiredTool
agent.add_tool(RequiredTool())

Tool Execution Failed

Error: Tool execution failed: [specific error]

Solution: 1. Enable detailed logging:

import logging
logging.basicConfig(level=logging.DEBUG)

2. Check tool prerequisites 3. Verify input parameters

Best Practices

1. Error Prevention

• Always verify API keys before starting
• Use virtual environments
• Keep dependencies updated
• Monitor system resources

2. Debugging

• Enable comprehensive logging
• Monitor all relevant events
• Use step-by-step execution
• Check system requirements

3. Performance

• Clean up unused resources
• Implement proper error handling
• Use batch processing when possible
• Monitor memory usage

Getting Help

If you're still stuck:

1. Search Documentation
2. Check this troubleshooting guide
3. Review relevant examples

4. Read tool documentation

5. Community Resources

6. Search GitHub Issues
7. Check Stack Overflow

8. Join Discord community

9. Support Channels

10. Open GitHub issue
11. Contact support team
12. Share detailed error logs

Reporting Bugs

When reporting issues:

1. Provide Context
2. Python version
3. QuantaLogic version
4. Operating system

5. Full error message

6. Share Reproduction Steps

7. Minimal code example
8. Input data (if relevant)

9. Expected vs actual result

10. Include Logs

11. Error messages
12. Event monitoring output
13. System information

Next Steps

• Review Best Practices
• Learn about Monitoring
• Check API Reference