379 lines
7.3 KiB
Markdown
379 lines
7.3 KiB
Markdown
# 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)
|