Skip to main content

Morphee Troubleshooting Guide

This guide helps you diagnose and resolve common issues with Morphee (V2.0 — Rust/axum backend).

For the legacy Python/FastAPI troubleshooting guide, see archive/troubleshooting-python.md.

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 a specific service
docker compose -f docker-compose.dev.yml logs morphee-server
docker compose -f docker-compose.dev.yml logs redis

Health Checks​

# Check morphee-server health
curl http://localhost:3000/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 :3000  # morphee-server
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. Morphee Server Not Responding​

Symptoms:

  • Connection refused on port 3000
  • morphee-server container keeps restarting
  • 500 errors on all endpoints

Diagnosis:

# Check morphee-server logs
docker compose -f docker-compose.dev.yml logs morphee-server

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

# Enter container for debugging
docker compose -f docker-compose.dev.yml exec morphee-server /bin/sh

Common Causes:

  1. Missing Environment Variables

    # Verify required MORPHEE_* env vars are set
    docker compose -f docker-compose.dev.yml exec morphee-server env | grep MORPHEE_

    # Key variables:
    # MORPHEE_DATABASE_URL — PostgreSQL connection string
    # MORPHEE_GOTRUE_URL — Supabase GoTrue endpoint
    # MORPHEE_SUPABASE_ANON_KEY — Supabase anonymous key
    # MORPHEE_SERVICE_ROLE_KEY — Service role key for admin operations

  2. Database Connection Issues

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

    # Test database connectivity
    docker compose -f docker-compose.dev.yml exec supabase-db psql -U morphee -d morphee -c "SELECT 1;"

  3. sqlx Migration Failures

    # Check migration status
    docker compose -f docker-compose.dev.yml logs morphee-server | grep -i migration

    # Manually run migrations (if supported)
    docker compose -f docker-compose.dev.yml exec morphee-server /app/morphee-server migrate

  4. Cargo Build Issues (local development)

    # Ensure Rust toolchain is available
    export PATH="$HOME/.cargo/bin:$PATH"
    rustc --version
    cargo --version

    # Clean and rebuild
    cd crates/morphee-server && cargo clean && cargo build

    # Check for missing system dependencies (OpenSSL, pkg-config)
    pkg-config --libs openssl

3. Database Connection Errors​

Symptoms:

  • "Connection refused" to PostgreSQL
  • morphee-server can't query database
  • sqlx 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:3000/v1/ws
# Or use browser console: new WebSocket('ws://localhost:3000/v1/ws')

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

# Verify Redis pub/sub is working
docker compose -f docker-compose.dev.yml exec redis redis-cli PSUBSCRIBE '*'

6. 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 morphee-server logs for slow operations
docker compose -f docker-compose.dev.yml logs morphee-server | grep -i "slow\|timeout"

Solutions:

  1. Increase Docker Resources — Docker Desktop settings, increase CPU/Memory
  2. Optimize Database 
    VACUUM ANALYZE;
  3. Connection Pooling — morphee-server uses sqlx connection pooling by default; check MORPHEE_DATABASE_MAX_CONNECTIONS if set

7. File Permission Errors​

Symptoms:

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

Solutions:

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

# For macOS with mounted volumes, add :delegated flag in docker-compose

8. 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 morphee-server env | grep MORPHEE_

# 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​

Set in .env or environment:

RUST_LOG=morphee_server=debug,morphee_core=debug

Restart morphee-server:

docker compose -f docker-compose.dev.yml restart morphee-server

Monitor Event Bus​

# Subscribe to all Redis events
docker compose -f docker-compose.dev.yml exec redis redis-cli PSUBSCRIBE '*'

Inspect Database State​

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

# Useful commands
\dt                          -- List all tables
\d tablename                 -- Describe table structure
SELECT * FROM users LIMIT 10;

Error Messages Reference​

See also: Error Code Catalog

ErrorCauseFix
"Database connection pool exhausted"Too many concurrent connectionsReduce load or increase pool size via MORPHEE_DATABASE_MAX_CONNECTIONS
"Redis connection lost"Redis server disconnectedCheck Redis is running; morphee-server auto-reconnects
"Migration failed"sqlx migration errorCheck logs, verify database schema, re-run migrations
"WASM extension load failed"Invalid or missing extension binaryVerify extension exists in storage, check binary compatibility

Reset to Clean State​

If all else fails:

# WARNING: This will delete all data!
docker compose -f docker-compose.dev.yml down -v
docker images | grep morphee | awk '{print $3}' | xargs docker rmi
docker system prune -a --volumes
docker compose -f docker-compose.dev.yml build --no-cache
docker compose -f docker-compose.dev.yml up -d
curl http://localhost:3000/health

Last Updated: February 28, 2026

For additional help, see: