Skip to main content

Troubleshooting

Common issues and how to resolve them.

Health Checks

Check if services are running:
curl http://localhost:3000/up  # Platform
curl http://localhost:4001/up  # Recall
curl http://localhost:4002/up  # Reflex

Container Issues

Container Won’t Start

Check logs:
docker compose logs platform
docker compose logs recall
docker compose logs reflex
Common causes:
  • Missing environment variables
  • Database connection failed
  • Port already in use

Out of Memory

Increase container memory:
services:
  platform:
    deploy:
      resources:
        limits:
          memory: 2G

Disk Full

Check disk usage:
docker system df
Clean up:
docker system prune -a

Database Issues

Connection Failed

PG::ConnectionBad: could not connect to server
  1. Check PostgreSQL is running:
    docker compose ps postgres
    
  2. Check connection string:
    docker compose exec platform rails dbconsole
    
  3. Check PostgreSQL logs:
    docker compose logs postgres
    

Migrations Failed

ActiveRecord::PendingMigrationError
Run migrations:
docker compose exec platform rails db:migrate
If stuck, check for locks:
SELECT * FROM pg_locks WHERE NOT granted;

Database Full

Check size:
SELECT pg_size_pretty(pg_database_size('brainzlab_recall'));
Enable retention:
LOG_RETENTION_DAYS=30
Run cleanup:
docker compose exec recall rails retention:cleanup

Redis Issues

Connection Failed

Redis::CannotConnectError
Check Redis is running:
docker compose ps redis
docker compose exec redis redis-cli ping

Memory Full

Check memory:
docker compose exec redis redis-cli info memory
Configure max memory:
# redis.conf
maxmemory 1gb
maxmemory-policy volatile-lru

Network Issues

Services Can’t Communicate

Check Docker network:
docker network ls
docker network inspect brainzlab_default
Verify service names resolve:
docker compose exec platform ping postgres
docker compose exec platform ping redis

SSL Certificate Errors

  1. Check certificate is valid:
    openssl x509 -in cert.pem -text -noout
    
  2. Ensure cert matches domain
  3. Check cert chain is complete

Performance Issues

Slow Queries

Enable query logging:
RAILS_LOG_LEVEL=debug
Check slow query log:
SELECT * FROM pg_stat_statements
ORDER BY total_time DESC
LIMIT 10;

High Memory Usage

Check process memory:
docker stats
Reduce workers:
WEB_CONCURRENCY=2
RAILS_MAX_THREADS=5

High CPU

Check which service:
docker stats
Scale horizontally or upgrade hardware.

Getting Help

If you’re still stuck:
  1. Check GitHub Issues
  2. Search Discussions
  3. Join Discord
  4. Contact support (paid plans)
Include in your report:
  • Version number
  • Error messages
  • Relevant logs
  • Steps to reproduce