Skip to content

Troubleshooting

Jump to bottom
AutoBotSolutions edited this page Apr 27, 2026 · 1 revision

Troubleshooting Guide

This guide helps you diagnose and resolve common issues with the Cognitive Engine.

Table of Contents

Installation Issues

Python Version Incompatible

Symptom: SyntaxError or module import errors after installation

Cause: Python version too old or incompatible

Solution:

# Check Python version
python --version

# Install Python 3.9 or higher
# On Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3.10 python3.10-venv

# On macOS with Homebrew
brew install python@3.10

# On Windows
# Download from https://www.python.org/downloads/

Dependencies Fail to Install

Symptom: pip install fails with build errors

Cause: Missing system dependencies or incompatible versions

Solution:

# Update pip
pip install --upgrade pip

# Install system dependencies
# Ubuntu/Debian
sudo apt-get install build-essential python3-dev

# macOS
xcode-select --install

# Try installing with specific versions
pip install -r requirements.txt --no-cache-dir

# If still failing, try:
pip install --upgrade setuptools wheel
pip install -r requirements.txt

Virtual Environment Issues

Symptom: Cannot activate virtual environment or modules not found

Cause: Incorrect virtual environment setup or activation

Solution:

# Remove existing venv
rm -rf venv

# Create new venv
python3 -m venv venv

# Activate correctly
# Linux/macOS
source venv/bin/activate

# Windows
venv\Scripts\activate

# Verify activation
which python  # Should show venv path

Configuration Issues

API Key Not Found

Symptom: API key not found or No LLM API key configured

Cause: Missing or incorrect environment variables

Solution:

# Check .env file exists
ls -la .env

# Create from example if missing
cp .env.example .env

# Edit .env and add keys
nano .env

# Verify keys are set
echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY

# If using Docker, pass environment variables
docker run -e OPENAI_API_KEY=your_key ...

Configuration Not Loading

Symptom: Default values used instead of configured values

Cause: .env file not in correct location or format incorrect

Solution:

# Ensure .env is in project root
pwd  # Should be cognitive_engine directory
ls .env

# Check format (no spaces around =)
# Correct: KEY=value
# Wrong: KEY = value

# Reload environment
source .env  # Linux/macOS
# or restart application

# Check for typos in variable names
# Should match exactly: OPENAI_API_KEY not OPENAIKEY

Port Already in Use

Symptom: Address already in use or Port 8000 already in use

Cause: Dashboard port or another service using the port

Solution:

# Find process using port
lsof -i :8000  # Linux/macOS
netstat -ano | findstr :8000  # Windows

# Kill the process
kill -9 <PID>  # Linux/macOS
taskkill /PID <PID> /F  # Windows

# Or change port in .env
DASHBOARD_PORT=8001

Runtime Issues

Engine Won't Start

Symptom: Application crashes immediately on startup

Cause: Missing dependencies, configuration errors, or import errors

Solution:

# Check error message in logs
tail -f cognitive_engine.log

# Run in verbose mode
LOG_LEVEL=DEBUG python run.py

# Check imports
python -c "from core.engine import CognitiveEngine"

# Verify all dependencies installed
pip list | grep -E "(openai|anthropic|pydantic|fastapi)"

# Reinstall if needed
pip install --force-reinstall -r requirements.txt

Import Errors

Symptom: ModuleNotFoundError: No module named 'xxx'

Cause: Module not installed or Python path issues

Solution:

# Ensure virtual environment activated
which python

# Install missing module
pip install <module_name>

# Check PYTHONPATH
echo $PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:/path/to/cognitive_engine"

# Reinstall all dependencies
pip install -r requirements.txt --force-reinstall

Process Hangs

Symptom: Application becomes unresponsive or hangs

Cause: Infinite loop, blocking operation, or deadlock

Solution:

# Check process status
ps aux | grep python

# Get stack trace (Linux)
kill -QUIT <PID>

# Check logs for loops
tail -f cognitive_engine.log

# Reduce iteration limits in config
MIN_ITERATIONS=1
MAX_ITERATIONS=10

# Enable debug logging
LOG_LEVEL=DEBUG

Performance Issues

Slow Response Times

Symptom: Queries take too long to complete

Cause: High iteration count, slow LLM, or inefficient code

Solution:

# Reduce iteration limits
MIN_ITERATIONS=1
MAX_ITERATIONS=20

# Use faster LLM provider
DEFAULT_LLM_PROVIDER=openai  # Generally faster than anthropic

# Enable caching if available
ENABLE_CACHING=true

# Check system resources
htop  # Linux/macOS
Task Manager  # Windows

# Profile the application
python -m cProfile -o profile.stats run.py
python -m pstats profile.stats

High CPU Usage

Symptom: CPU usage near 100%

Cause: Intensive computation or infinite loop

Solution:

# Check what's using CPU
top -p <PID>

# Reduce cognitive iterations
MAX_ITERATIONS=30

# Disable expensive features
ENABLE_LEARNING=false
ENABLE_PROMPT_EVOLUTION=false

# Add rate limiting
RATE_LIMIT_REQUESTS_PER_MINUTE=60

High Memory Usage

Symptom: Memory usage grows continuously

Cause: Memory leak or unbounded memory growth

Solution:

# Check memory usage
free -h  # Linux
vm_stat  # macOS

# Limit memory size
MAX_MEMORY_SIZE=5000

# Enable memory cleanup
ENABLE_MEMORY_CLEANUP=true

# Clear memory periodically
python run.py cleanup

# Check for memory leaks
pip install memory_profiler
python -m memory_profiler run.py

Memory Issues

Database Locked

Symptom: SQLite database is locked

Cause: Multiple processes accessing database simultaneously

Solution:

# Check for other processes
ps aux | grep python

# Stop other instances
pkill -f "python run.py"

# Use WAL mode for better concurrency
# Add to database initialization
PRAGMA journal_mode=WAL;

# Or use PostgreSQL for production
DATABASE_URL=postgresql://user:pass@localhost/db

Memory Not Persisting

Symptom: Memory lost after restart

Cause: Database path incorrect or permissions issue

Solution:

# Check database file exists
ls -la cognitive_engine.db

# Check permissions
chmod 644 cognitive_engine.db

# Verify path in config
MEMORY_DB_PATH=cognitive_engine.db

# Use absolute path
MEMORY_DB_PATH=/full/path/to/cognitive_engine.db

# Check disk space
df -h

Memory Corruption

Symptom: Strange data in memory or crashes

Cause: Database corruption or concurrent access

Solution:

# Backup current database
cp cognitive_engine.db cognitive_engine.db.backup

# Try to repair
sqlite3 cognitive_engine.db "PRAGMA integrity_check;"

# If corrupted, restore from backup
cp cognitive_engine.db.backup cognitive_engine.db

# Start fresh if needed
rm cognitive_engine.db
python run.py  # Will recreate

LLM API Issues

API Key Invalid

Symptom: Invalid API key or 401 Unauthorized

Cause: Incorrect API key or key revoked

Solution:

# Verify key is correct
echo $OPENAI_API_KEY

# Regenerate key from provider
# OpenAI: https://platform.openai.com/api-keys
# Anthropic: https://console.anthropic.com/

# Update .env file
nano .env

# Restart application

Rate Limit Exceeded

Symptom: Rate limit exceeded or 429 Too Many Requests

Cause: Too many API requests in short time

Solution:

# Implement exponential backoff
# Already handled in client, but can tune
RETRY_DELAY=1
MAX_RETRIES=3

# Reduce request frequency
# Add delay between requests
REQUEST_DELAY=0.5

# Upgrade API plan
# OpenAI: https://platform.openai.com/account/billing
# Anthropic: https://console.anthropic.com/settings/billing

# Use caching
ENABLE_RESPONSE_CACHE=true
CACHE_TTL=3600

API Timeout

Symptom: Request times out after long wait

Cause: Network issues or slow LLM response

Solution:

# Increase timeout
LLM_TIMEOUT=60

# Check network connectivity
ping api.openai.com
ping api.anthropic.com

# Use faster model
DEFAULT_MODEL=gpt-3.5-turbo  # Instead of gpt-4

# Check provider status
# OpenAI: https://status.openai.com/
# Anthropic: https://status.anthropic.com/

Insufficient Quota

Symptom: Insufficient quota or billing error

Cause: API quota exceeded or billing issue

Solution:

# Check quota/billing
# OpenAI: https://platform.openai.com/account/usage
# Anthropic: https://console.anthropic.com/settings/billing

# Add credits or upgrade plan

# Monitor usage
python run.py monitor-usage

Dashboard Issues

Dashboard Not Accessible

Symptom: Cannot access dashboard at http://localhost:8000

Cause: Dashboard not enabled or wrong port

Solution:

# Check dashboard enabled
ENABLE_DASHBOARD=true

# Check correct port
DASHBOARD_PORT=8000

# Verify server running
ps aux | grep "python run.py"

# Check firewall
sudo ufw allow 8000  # Linux
# Windows Firewall settings

# Try different port
DASHBOARD_PORT=8080

WebSocket Connection Failed

Symptom: WebSocket connection failed in browser console

Cause: WebSocket not enabled or blocked

Solution:

# Check WebSocket enabled
ENABLE_WEBSOCKET=true

# Check browser console for errors
# F12 → Console tab

# Try different browser
# Chrome, Firefox, Safari

# Check for proxy issues
# Disable VPN or proxy temporarily

# Verify WebSocket URL
ws://localhost:8000/ws

Dashboard Not Updating

Symptom: Dashboard shows stale data or no updates

Cause: Event stream not working or client disconnected

Solution:

# Check server logs
tail -f cognitive_engine.log

# Refresh browser page
# Ctrl+Shift+R (hard refresh)

# Check WebSocket connection
# Browser console → Network tab → WS

# Restart dashboard
python run.py dashboard

Agent Issues

Agent Not Responding

Symptom: Agent accepts goal but doesn't produce output

Cause: Goal validation failing or tool error

Solution:

# Check goal validation
AGENT_GOAL_VALIDATION=false  # Disable temporarily

# Check tool availability
python run.py list-tools

# Check agent logs
tail -f cognitive_engine.log | grep agent

# Try simple goal
python run.py agent "What is 2+2?"

Tool Execution Fails

Symptom: Agent tool calls fail with errors

Cause: Tool not registered or invalid parameters

Solution:

# Check tool registry
python run.py check-tools

# Verify tool permissions
TOOL_PERMISSIONS=permissive

# Check tool-specific configuration
# e.g., for web search
WEB_SEARCH_API_KEY=your_key

# Test tool directly
python -c "from tools.web_search import WebSearchTool; tool = WebSearchTool(); print(tool.search('test'))"

Agent Loops

Symptom: Agent repeats same actions indefinitely

Cause: Missing step limit or goal unclear

Solution:

# Set step limit
AGENT_STEP_LIMIT=50

# Clarify goal
# Be more specific in goal description

# Enable goal validation
AGENT_GOAL_VALIDATION=true

# Check logs for patterns
tail -f cognitive_engine.log

Learning System Issues

Patterns Not Extracting

Symptom: Learning system not finding patterns

Cause: Insufficient data or threshold too high

Solution:

# Check learning enabled
ENABLE_LEARNING=true

# Lower pattern threshold
PATTERN_THRESHOLD=3

# Check memory has data
python run.py check-memory

# Force pattern extraction
python run.py extract-patterns

Rules Not Applying

Symptom: Learned rules not being used

Cause: Rules not synthesized or effectiveness too low

Solution:

# Check rule effectiveness threshold
RULE_EFFECTIVENESS_THRESHOLD=0.5

# Force rule synthesis
python run.py synthesize-rules

# Check rule memory
python run.py list-rules

# Manually apply rules
python run.py apply-rules

Learning Too Slow

Symptom: Learning operations take too long

Cause: Too much data or inefficient extraction

Solution:

# Increase learning interval
LEARNING_INTERVAL=500

# Reduce memory size
MAX_MEMORY_SIZE=5000

# Disable learning temporarily
ENABLE_LEARNING=false

# Clear old memory
python run.py clear-old-memory

Database Issues

Database Connection Failed

Symptom: Cannot connect to database

Cause: Database not running or wrong credentials

Solution:

# Check database file exists
ls -la cognitive_engine.db

# Check permissions
chmod 644 cognitive_engine.db

# Try with absolute path
MEMORY_DB_PATH=/full/path/to/cognitive_engine.db

# Recreate database
rm cognitive_engine.db
python run.py

Query Performance Slow

Symptom: Database queries take too long

Cause: Missing indexes or large dataset

Solution:

# Add indexes
# In database initialization
CREATE INDEX IF NOT EXISTS idx_timestamp ON episodic_memory(timestamp);

# Vacuum database
sqlite3 cognitive_engine.db "VACUUM;"

# Reduce dataset size
MAX_MEMORY_SIZE=10000

# Consider PostgreSQL for production
DATABASE_URL=postgresql://user:pass@localhost/db

Database File Too Large

Symptom: Database file growing too large

Cause: Unbounded memory growth

Solution:

# Set memory limit
MAX_MEMORY_SIZE=10000

# Enable retention policy
MEMORY_RETENTION_DAYS=90

# Clear old data
python run.py clear-old-memory

# Backup and recreate
cp cognitive_engine.db backup.db
rm cognitive_engine.db
python run.py

Getting Help

Diagnostic Information

Before seeking help, gather diagnostic information:

# System information
python --version
pip list
uname -a  # Linux/macOS
systeminfo  # Windows

# Configuration
cat .env

# Logs (last 100 lines)
tail -100 cognitive_engine.log

# Memory status
python run.py status

# Database check
sqlite3 cognitive_engine.db "PRAGMA integrity_check;"

Log Files

Check log files for error messages:

# Main log
tail -f cognitive_engine.log

# Debug log
LOG_LEVEL=DEBUG python run.py 2>&1 | tee debug.log

# System logs
journalctl -u cognitive-engine  # systemd
/var/log/syslog  # Linux system log

Common Error Messages

Error Cause Solution
ModuleNotFoundError Missing module pip install <module>
API key not found Missing API key Set in .env
Database locked Concurrent access Use WAL mode or PostgreSQL
Rate limit exceeded Too many requests Implement backoff, upgrade plan
Port already in use Port conflict Change port or kill process
Permission denied File permissions chmod 644 file
Out of memory Memory limit reached Increase memory or reduce usage

Support Channels

  • Email: autobotsolution@gmail.com
  • Address: Flushing MI
  • GitHub Issues: Check existing issues first
  • Documentation: Review relevant wiki pages
  • Logs: Always include log excerpts

When Reporting Issues

Include:

  1. Python version
  2. Operating system
  3. Error message (full traceback)
  4. Configuration (sanitized)
  5. Steps to reproduce
  6. Expected vs actual behavior
  7. Log excerpts (relevant sections)

Debug Mode

Enable debug mode for more information:

# Set debug log level
LOG_LEVEL=DEBUG

# Enable verbose output
VERBOSE=true

# Run with Python debugger
python -m pdb run.py

# Or use breakpoint() in code

Clean Slate

If all else fails, start fresh:

# Backup current state
cp -r cognitive_engine cognitive_engine.backup
cp .env .env.backup
cp cognitive_engine.db cognitive_engine.db.backup

# Remove virtual environment
rm -rf venv

# Remove database
rm cognitive_engine.db

# Remove logs
rm cognitive_engine.log

# Recreate everything
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python run.py

Prevention

Regular Maintenance

# Update dependencies
pip install --upgrade -r requirements.txt

# Clear old memory
python run.py cleanup

# Backup database
cp cognitive_engine.db backup/cognitive_engine_$(date +%Y%m%d).db

# Check disk space
df -h

# Monitor logs
tail -f cognitive_engine.log

Health Checks

# Run health check
python run.py health

# Check all components
python run.py check-all

# Test configuration
python run.py test-config

Monitoring

Set up monitoring for:

  • Error rates
  • Response times
  • Memory usage
  • CPU usage
  • Disk space
  • API quota usage

Clone this wiki locally