# 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](common-errors.md)

Frequently encountered error messages:

- Error codes and meanings
- Stack trace interpretation
- Quick fixes
- When to escalate

### [FAQ](faq.md)

Frequently asked questions:

- Installation questions
- Configuration questions
- Feature questions
- Troubleshooting tips

### [Docker Issues](docker-issues.md)

Container and orchestration problems:

- Container won't start
- Port conflicts
- Volume permission errors
- Network connectivity
- Resource constraints

### [Database Issues](database-issues.md)

PostgreSQL and Prisma problems:

- Connection errors
- Migration failures
- Query performance
- Data corruption
- Backup/restore issues

### [Authentication Issues](auth-issues.md)

Login and permission problems:

- Can't log in
- Token expired
- Invalid credentials
- Role permission denied
- Session management

### [Email Issues](email-issues.md)

Email delivery problems:

- SMTP connection failed
- Emails not sending
- Queue backed up
- Template errors
- Test mode not working

### [Geocoding Issues](geocoding-issues.md)

Address geocoding problems:

- Geocoding fails
- Wrong coordinates
- Provider errors
- Rate limiting
- Bulk geocoding stuck

### [Monitoring Issues](monitoring-issues.md)

Observability and metrics problems:

- Prometheus not scraping
- Grafana dashboard errors
- Alert not firing
- Metrics missing
- Service health incorrect

### [Performance Optimization](performance-optimization.md)

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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

- [Common Errors](common-errors.md)
- [FAQ](faq.md)
- [Docker Issues](docker-issues.md)
- [Database Issues](database-issues.md)
- [Authentication Issues](auth-issues.md)
- [Email Issues](email-issues.md)
- [Geocoding Issues](geocoding-issues.md)
- [Monitoring Issues](monitoring-issues.md)
- [Performance Optimization](performance-optimization.md)
- [Development Guide](../development/index.md)
- [Deployment Guide](../deployment/index.md)