admin/changemaker.lite
1
0
Fork 0
Code Issues Packages Projects Releases 31 Wiki Activity
changemaker.lite/mkdocs/docs/v2/troubleshooting/index.md

7.3 KiB
Raw Blame History

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

P2002: Unique constraint failed

Cause: Duplicate value for unique field (email, slug, etc.) Fix: Use different value or update existing record

P2025: Record not found

Cause: Trying to access non-existent record Fix: Verify ID exists, check deletion

P2021: Table does not exist

Cause: Missing migration Fix: Run npx prisma migrate deploy

API Errors

401 Unauthorized

Cause: Missing/invalid JWT token Fix: Login again, check token expiration

403 Forbidden

Cause: Insufficient permissions Fix: Check user role, verify RBAC middleware

429 Too Many Requests

Cause: Rate limit exceeded Fix: Wait, reduce request frequency

Docker Errors

port is already allocated

Cause: Port conflict Fix: Stop conflicting service, change port in docker-compose.yml

no space left on device

Cause: Disk full Fix: Clean up: docker system prune -a

network not found

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

Related Documentation