Troubleshooting Guide¶
This section covers common issues, error messages, and solutions for Changemaker Lite V2. Use this guide to diagnose and resolve problems with installation, configuration, and operation.
Quick Reference¶
Common Errors¶
Frequently encountered error messages:
- Error codes and meanings
- Stack trace interpretation
- Quick fixes
- When to escalate
FAQ¶
Frequently asked questions:
- Installation questions
- Configuration questions
- Feature questions
- Troubleshooting tips
Docker Issues¶
Container and orchestration problems:
- Container won't start
- Port conflicts
- Volume permission errors
- Network connectivity
- Resource constraints
Database Issues¶
PostgreSQL and Prisma problems:
- Connection errors
- Migration failures
- Query performance
- Data corruption
- Backup/restore issues
Authentication Issues¶
Login and permission problems:
- Can't log in
- Token expired
- Invalid credentials
- Role permission denied
- Session management
Email Issues¶
Email delivery problems:
- SMTP connection failed
- Emails not sending
- Queue backed up
- Template errors
- Test mode not working
Geocoding Issues¶
Address geocoding problems:
- Geocoding fails
- Wrong coordinates
- Provider errors
- Rate limiting
- Bulk geocoding stuck
Monitoring Issues¶
Observability and metrics problems:
- Prometheus not scraping
- Grafana dashboard errors
- Alert not firing
- Metrics missing
- Service health incorrect
Performance Optimization¶
Speed and efficiency improvements:
- Slow API responses
- Database query optimization
- Frontend performance
- Cache optimization
- Resource usage
Common Issues¶
Installation Problems¶
Symptom: Docker containers fail to start
Common Causes: - Port conflicts - Missing environment variables - Insufficient resources - Corrupted volumes
Solutions:
1. Check port availability: netstat -tulpn | grep <port>
2. Verify .env file exists and is complete
3. Increase Docker memory/CPU limits
4. Remove volumes: docker compose down -v
Symptom: Database migration fails
Common Causes: - Database not running - Connection string incorrect - Migration conflict - Permission issues
Solutions:
1. Verify PostgreSQL is running: docker compose ps
2. Check DATABASE_URL in .env
3. Reset database (dev only): npx prisma migrate reset
4. Check user permissions
Symptom: "Cannot connect to Redis"
Common Causes: - Redis not started - Wrong password - Port conflict - Network issue
Solutions:
1. Start Redis: docker compose up -d redis
2. Verify REDIS_PASSWORD matches in all services
3. Check port 6379 not in use
4. Test connection: docker compose exec redis redis-cli ping
Runtime Problems¶
Symptom: API returns 500 errors
Common Causes: - Unhandled exception - Database query error - Service unavailable - Configuration issue
Solutions:
1. Check API logs: docker compose logs -f api
2. Review error stack trace
3. Test database connection
4. Verify environment variables
Symptom: Frontend shows blank page
Common Causes: - Build error - API not reachable - CORS issue - JavaScript error
Solutions:
1. Check browser console (F12)
2. Verify VITE_API_URL in .env
3. Check nginx CORS headers
4. Rebuild admin: docker compose build admin
Symptom: Emails not sending
Common Causes: - SMTP credentials wrong - Test mode enabled - Queue worker not running - Network blocked
Solutions:
1. Check EMAIL_TEST_MODE setting
2. Verify SMTP settings in .env
3. Check email queue: docker compose logs -f api | grep email
4. Test with MailHog (port 8025)
Configuration Issues¶
Symptom: Subdomain routing not working
Common Causes: - Nginx config error - DNS not set up - Tunnel not configured - Certificate issue
Solutions:
1. Check nginx config: docker compose exec nginx nginx -t
2. Verify DNS records
3. Review tunnel status in Pangolin page
4. Check SSL certificate validity
Symptom: Feature not working (media, listmonk, etc.)
Common Causes: - Feature flag disabled - Service not started - API credentials missing - Integration not configured
Solutions:
1. Check feature flag in .env (e.g., ENABLE_MEDIA_FEATURES)
2. Start required services: docker compose up -d <service>
3. Verify API keys/credentials
4. Complete setup wizard in admin
Diagnostic Commands¶
Check Service Status¶
# All services
docker compose ps
# Specific service
docker compose ps api
# Service logs
docker compose logs -f api
docker compose logs --tail=100 v2-postgres
Test Connectivity¶
# API health check
curl http://localhost:4000/health
# Database connection
docker compose exec api npx prisma db execute --stdin <<< "SELECT 1"
# Redis connection
docker compose exec redis redis-cli ping
Database Diagnostics¶
# Open Prisma Studio
cd api && npx prisma studio
# Check migrations
cd api && npx prisma migrate status
# View database
docker compose exec v2-postgres psql -U changemaker -d changemaker_v2
View Logs¶
# All services
docker compose logs -f
# Specific service
docker compose logs -f api
docker compose logs -f admin
# Error logs only
docker compose logs -f | grep ERROR
Resource Usage¶
# Docker stats
docker stats
# Disk usage
docker system df
# Container resource limits
docker compose config | grep mem_limit
Error Message Reference¶
Database Errors¶
Cause: Duplicate value for unique field (email, slug, etc.) Fix: Use different value or update existing record Cause: Trying to access non-existent record Fix: Verify ID exists, check deletion Cause: Missing migration Fix: Runnpx prisma migrate deploy
API Errors¶
Cause: Missing/invalid JWT token Fix: Login again, check token expiration Cause: Insufficient permissions Fix: Check user role, verify RBAC middleware Cause: Rate limit exceeded Fix: Wait, reduce request frequencyDocker Errors¶
Cause: Port conflict Fix: Stop conflicting service, change port in docker-compose.yml Cause: Disk full Fix: Clean up:docker system prune -a
Cause: Docker network missing
Fix: Recreate: docker compose down && docker compose up -d
When to Get Help¶
Escalate to GitHub issues if:
- Error persists after troubleshooting
- Data corruption or loss
- Security vulnerability discovered
- Bug in core functionality
- Documentation unclear