Skip to main content

Morphee Troubleshooting Guide

This guide helps you diagnose and resolve common issues with Morphee.

Quick Diagnostics​

Check System Status​

# Check all services are running
docker compose -f docker-compose.dev.yml ps

# View logs for all services
docker compose -f docker-compose.dev.yml logs

# View logs for specific service
docker compose -f docker-compose.dev.yml logs backend
docker compose -f docker-compose.dev.yml logs redis

Health Checks​

# Check backend API health
curl http://localhost:8000/health

# Check Redis connectivity
docker compose -f docker-compose.dev.yml exec redis redis-cli ping

Common Issues​

1. Docker Services Won't Start​

Symptoms:

  • Services fail to start
  • Port already in use errors
  • Container exits immediately

Solutions:

# Check if ports are already in use
lsof -i :8000  # Backend
lsof -i :5432  # PostgreSQL
lsof -i :6379  # Redis

# Stop all containers and restart
docker compose -f docker-compose.dev.yml down
docker compose -f docker-compose.dev.yml up -d

# Rebuild containers if needed
docker compose -f docker-compose.dev.yml down
docker compose -f docker-compose.dev.yml build --no-cache
docker compose -f docker-compose.dev.yml up -d

# Check Docker disk space
docker system df
docker system prune  # Clean up if needed

2. Backend API Not Responding​

Symptoms:

  • Connection refused on port 8000
  • Backend container keeps restarting
  • 500 errors on all endpoints

Diagnosis:

# Check backend logs
docker compose -f docker-compose.dev.yml logs backend

# Check if backend container is running
docker compose -f docker-compose.dev.yml ps backend

# Enter backend container for debugging
docker compose -f docker-compose.dev.yml exec backend /bin/bash

Common Causes:

  1. Missing Environment Variables

    # Verify .env file exists
    ls -la .env

    # Check required variables are set
    grep -E "DATABASE_URL|REDIS_URL|JWT_SECRET" .env

  2. Database Connection Issues

    # Check DATABASE_URL format
    # Should be: postgresql://user:password@host:port/database

    # Test database connectivity from backend container
    docker compose -f docker-compose.dev.yml exec backend python -c "
    import asyncio
    from db.client import get_db
    async def check():
        db = get_db()
        await db.initialize()
        print('DB connected:', await db.health_check())
    asyncio.run(check())
    "

  3. Python Dependencies Missing

    # Rebuild backend container
    docker compose -f docker-compose.dev.yml build backend
    docker compose -f docker-compose.dev.yml up -d backend

3. Database Connection Errors​

Symptoms:

  • "Connection refused" to PostgreSQL
  • Backend can't query database
  • asyncpg connection pool errors

Solutions:

# Check PostgreSQL is running
docker compose -f docker-compose.dev.yml ps supabase-db

# Check PostgreSQL logs
docker compose -f docker-compose.dev.yml logs supabase-db

# Connect to PostgreSQL directly
docker compose -f docker-compose.dev.yml exec supabase-db psql -U morphee -d morphee

# Run migrations if tables are missing
docker compose -f docker-compose.dev.yml exec supabase-db psql -U morphee -d morphee -f /docker-entrypoint-initdb.d/001_core_tables.sql

4. Redis Connection Issues​

Symptoms:

  • Events not publishing/receiving
  • WebSocket updates not working
  • "Connection refused" to Redis

Solutions:

# Check Redis is running
docker compose -f docker-compose.dev.yml ps redis

# Test Redis connectivity
docker compose -f docker-compose.dev.yml exec redis redis-cli ping
# Should return: PONG

# Check Redis memory usage
docker compose -f docker-compose.dev.yml exec redis redis-cli INFO memory

# Clear Redis cache if needed
docker compose -f docker-compose.dev.yml exec redis redis-cli FLUSHALL

5. WebSocket Connection Failures​

Symptoms:

  • WebSocket connection fails
  • No real-time updates
  • Browser shows WebSocket error

Solutions:

# Check WebSocket endpoint
wscat -c ws://localhost:8000/ws
# Or use browser console: new WebSocket('ws://localhost:8000/ws')

# Check backend logs for WebSocket errors
docker compose -f docker-compose.dev.yml logs backend | grep -i websocket

# Verify Redis pub/sub is working
docker compose -f docker-compose.dev.yml exec redis redis-cli
# In Redis CLI:
> SUBSCRIBE task:*
# Then in another terminal, trigger an event and check if message is received

6. Interface Registration Failures​

Symptoms:

  • Interface not showing in /interfaces list
  • Action execution fails with "Interface not found"
  • Import errors for custom interfaces

Solutions:

# Check interface file is in correct location
ls -la backend/interfaces/integrations/

# Verify interface is registered in manager.py
docker compose -f docker-compose.dev.yml exec backend python -c "
from interfaces.manager import InterfaceManager
manager = InterfaceManager()
print('Registered interfaces:', list(manager.interfaces.keys()))
"

# Check for Python import errors
docker compose -f docker-compose.dev.yml exec backend python -c "
from interfaces.integrations.your_interface import YourInterface
print('Import successful')
"

# Restart backend to re-register interfaces
docker compose -f docker-compose.dev.yml restart backend

7. Test Failures​

Symptoms:

  • Tests fail unexpectedly
  • Import errors in tests
  • Database state issues in tests

Solutions:

# Run tests with verbose output
docker compose -f docker-compose.dev.yml exec backend pytest -v

# Run specific test file
docker compose -f docker-compose.dev.yml exec backend pytest tests/test_interfaces.py -v

# Clear pytest cache
docker compose -f docker-compose.dev.yml exec backend pytest --cache-clear

# Check test dependencies installed
docker compose -f docker-compose.dev.yml exec backend pip list | grep pytest

8. Performance Issues​

Symptoms:

  • Slow API response times
  • High CPU/memory usage
  • Database queries taking too long

Diagnosis:

# Check Docker resource usage
docker stats

# Check PostgreSQL slow queries
docker compose -f docker-compose.dev.yml exec supabase-db psql -U morphee -d morphee -c "
SELECT query, mean_exec_time, calls
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;"

# Monitor backend logs for slow operations
docker compose -f docker-compose.dev.yml logs backend | grep -i "slow\|timeout"

Solutions:

  1. Increase Docker Resources

    • Docker Desktop → Settings → Resources
    • Increase CPU/Memory allocation

  2. Optimize Database

    -- Add indexes for frequently queried columns
    CREATE INDEX idx_tasks_status ON tasks(status);
    CREATE INDEX idx_tasks_created_at ON tasks(created_at);

    -- Vacuum and analyze
    VACUUM ANALYZE;

  3. Add Connection Pooling

    • Consider using PgBouncer for production
    • Limit concurrent connections in config

9. File Permission Errors​

Symptoms:

  • Permission denied errors
  • Can't write logs
  • Volume mount issues

Solutions:

# Fix permissions on local directories
sudo chown -R $(whoami):$(whoami) .
chmod -R 755 .

# For macOS users with mounted volumes
# Add to docker-compose.dev.yml under volumes:
volumes:
  - ./backend:/app:delegated  # Add :delegated flag

10. Environment Configuration Issues​

Symptoms:

  • Settings not being applied
  • Wrong database connection
  • Incorrect secrets

Solutions:

# Verify .env file is loaded
docker compose -f docker-compose.dev.yml config

# Check environment variables in container
docker compose -f docker-compose.dev.yml exec backend env | grep -E "DATABASE|REDIS|JWT"

# Recreate containers to reload environment
docker compose -f docker-compose.dev.yml down
docker compose -f docker-compose.dev.yml up -d

Debugging Techniques​

Enable Debug Logging​

Add to .env:

LOG_LEVEL=DEBUG
PYTHONDONTWRITEBYTECODE=1

Restart backend:

docker compose -f docker-compose.dev.yml restart backend

Interactive Python Debugging​

# Enter backend container
docker compose -f docker-compose.dev.yml exec backend /bin/bash

# Start Python REPL
python

# Import and test components
>>> from interfaces.manager import InterfaceManager
>>> manager = InterfaceManager()
>>> print(manager.list_interfaces())

Monitor Event Bus​

# Subscribe to all Redis events
docker compose -f docker-compose.dev.yml exec redis redis-cli
> PSUBSCRIBE *
# Keep this running and trigger actions to see events

Inspect Database State​

# Connect to PostgreSQL
docker compose -f docker-compose.dev.yml exec supabase-db psql -U morphee -d morphee

# Useful queries
\dt                          # List all tables
SELECT * FROM tasks LIMIT 10;
SELECT * FROM task_logs ORDER BY created_at DESC LIMIT 10;
\d tasks                     # Describe tasks table structure

Getting Help​

Collect Diagnostic Information​

Before reporting an issue, collect:

# System information
uname -a
docker --version
docker-compose --version

# Service status
docker compose -f docker-compose.dev.yml ps

# Recent logs (last 100 lines)
docker compose -f docker-compose.dev.yml logs --tail=100 > logs.txt

# Environment configuration (remove secrets!)
docker compose -f docker-compose.dev.yml config > config.txt

Reset to Clean State​

If all else fails, reset everything:

# WARNING: This will delete all data!

# Stop and remove all containers, volumes, and networks
docker compose -f docker-compose.dev.yml down -v

# Remove all morphee-related Docker images
docker images | grep morphee | awk '{print $3}' | xargs docker rmi

# Remove all unused Docker resources
docker system prune -a --volumes

# Rebuild from scratch
docker compose -f docker-compose.dev.yml build --no-cache
docker compose -f docker-compose.dev.yml up -d

# Verify services are healthy
docker compose -f docker-compose.dev.yml ps
curl http://localhost:8000/health

Error Messages Reference​

See also: Error Code Catalog for a comprehensive list of all error codes and messages.

"Interface not found"​

  • Cause: Interface not registered or misspelled name
  • Fix: Check interface name, verify registration in manager.py

"Action not found for interface"​

  • Cause: Action method doesn't exist or not properly defined
  • Fix: Verify action exists in interface class, check method signature

"Invalid parameters for action"​

  • Cause: Missing required parameters or wrong parameter types
  • Fix: Check action definition, provide all required parameters with correct types

"Task execution timeout"​

  • Cause: Action took longer than timeout limit (30s default)
  • Fix: Optimize action logic or increase timeout in executor

"Database connection pool exhausted"​

  • Cause: Too many concurrent database connections
  • Fix: Reduce concurrent requests or increase pool size

"Redis connection lost"​

  • Cause: Redis server disconnected or restarted
  • Fix: Check Redis is running, backend should auto-reconnect

Best Practices​

Development Environment​

  1. Always check logs first: docker-compose logs
  2. Use health checks: Verify services before debugging code
  3. Keep containers updated: Rebuild after dependency changes
  4. Monitor resources: Check Docker stats regularly
  5. Version control .env: Keep .env.example updated

Production Environment​

  1. Implement proper monitoring: Use Prometheus/Grafana
  2. Set up alerting: Get notified of issues immediately
  3. Regular backups: Automate database backups
  4. Load testing: Test system under expected load
  5. Security audits: Regular dependency and security scans

Last Updated: February 13, 2026

For additional help, see: