changemaker.lite/mkdocs/docs/docs/troubleshooting/index.md

title, description, icon, tags, search

title	description	icon	tags	search
Troubleshooting	Solutions for common errors, CORS issues, database problems, and tunnel debugging.	material/bug	troubleshooting operator	boost 2

Troubleshooting

Common issues and their solutions when running Changemaker Lite.

---

CORS Errors in Production

Symptom: Browser console shows CORS errors when accessing production domain.

Fix: Add your production domain to CORS_ORIGINS in .env:

CORS_ORIGINS=https://app.yourdomain.org,http://localhost:3000

Then restart the API: docker compose restart api

---

Pangolin Tunnel — 403/302 Errors

Symptom: All API endpoints return 302 redirects to Pangolin auth page, or 403 Forbidden.

Fix: In the Pangolin dashboard, set each resource to Not Protected (public access). Critical resources to fix first:

1. api.yourdomain.org — Main API
2. app.yourdomain.org — Admin GUI + public pages
3. media.yourdomain.org — Media API

Verify:

# Should return JSON, NOT a 302 redirect
curl -I https://api.yourdomain.org/api/health

---

Database Connection Failures

Symptom: API logs show database connection errors.

Checklist:

1. Check PostgreSQL: docker compose ps v2-postgres
2. Verify DATABASE_URL in .env matches container name and port
3. View logs: docker compose logs v2-postgres --tail 50
4. Test connection: docker compose exec api npx prisma db execute --stdin <<< "SELECT 1"

---

Redis Connection Failures

Symptom: API logs show Redis connection errors, rate limiting doesn't work.

Checklist:

1. Check Redis: docker compose ps redis-changemaker
2. Verify REDIS_PASSWORD and REDIS_URL format (redis://:password@host:port)
3. View logs: docker compose logs redis-changemaker --tail 50
4. Test: docker compose exec redis-changemaker redis-cli -a $REDIS_PASSWORD ping

---

API Not Starting

Symptom: API container keeps restarting or won't start.

Checklist:

1. Check logs: docker compose logs api --tail 100
2. Verify all required env vars are set (compare with .env.example)
3. Check database is ready: docker compose ps v2-postgres (should show "healthy")
4. Run migrations manually: docker compose exec api npx prisma migrate deploy
5. Check for port conflicts: ss -tlnp | grep 4000

---

Containers in Restart Loops

Symptom: docker compose ps shows containers with "restarting" status.

Diagnosis:

# Find restarting containers
docker compose ps | grep -i restarting

# Check recent logs for the problem container
docker compose logs <service-name> --tail 50

# Check container exit code
docker inspect <container-name> --format='{{.State.ExitCode}}'

Common causes:

• Missing environment variables (check .env)
• Database not ready (healthcheck dependencies)
• Port already in use by another process
• Insufficient memory (check with free -h)

---

Newt Tunnel Won't Connect

Checklist (in order):

1. Credentials: Verify PANGOLIN_NEWT_ID and PANGOLIN_NEWT_SECRET in .env
2. Endpoint: Confirm PANGOLIN_ENDPOINT matches your Pangolin server URL
3. Logs: docker compose logs newt --tail 50
4. Nginx running: Newt depends on nginx — docker compose ps nginx
5. Network: Ensure outbound HTTPS is not blocked by your firewall

---

Migration Errors

Symptom: prisma migrate deploy fails.

Common fixes:

# Check migration status
docker compose exec api npx prisma migrate status

# If migrations are out of sync, reset (DESTRUCTIVE — dev only)
docker compose exec api npx prisma migrate reset

# If shadow database errors, create one
docker compose exec -T v2-postgres createdb -U changemaker prisma_shadow_diff

!!! danger "Never use prisma db push in production" Always use prisma migrate dev (development) or prisma migrate deploy (production) to keep migration history in sync.

---

Media API Upload Failures

Symptom: Video uploads fail with permission errors or 500 status.

Checklist:

1. Verify inbox volume is writable: check media/local/inbox has :rw mount
2. Check disk space: df -h
3. Verify FFmpeg is installed in container: docker compose exec media-api ffprobe -version
4. Check upload size limit: default is 10 GB in Fastify multipart config

---

Email Not Sending

Symptom: Advocacy emails or notifications aren't delivered.

Checklist:

1. Check EMAIL_TEST_MODE — if true, all emails go to MailHog (http://localhost:8025)
2. Verify SMTP credentials in .env (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS)
3. Check BullMQ queue: visit Admin > Email Queue or check logs
4. Test SMTP from Settings: Admin > Settings > Email > Test Connection

---

Services Unreachable via Tunnel

Checklist:

1. Verify nginx is running: docker compose ps nginx
2. Test locally first: curl http://localhost:4000/api/health
3. Check nginx logs: docker compose logs nginx --tail 50
4. Verify DNS: dig app.yourdomain.org should point to your Pangolin server
5. Check Pangolin resources are all set to "Not Protected"

---

Slow Map Performance

Symptom: Map page is slow or returns 500 errors with many locations.

Causes and fixes:

• Too many locations loaded at once — the API limits by address count with debounced bounds queries
• Missing indexes — verify database has the 5 performance indexes on Location/Address tables
• Browser memory — marker clustering activates above zoom level 18; below that, addresses are grouped

---

Docker Disk Space

Symptom: Builds fail, containers can't start, or images won't pull.

# Check disk usage
df -h

# Clean unused Docker resources
docker system prune -f

# Clean old images (keep only last 2 days)
docker image prune -a --filter "until=48h"

# Check what's using space
docker system df

---

Getting Help

If your issue isn't listed here:

1. Check the API logs: docker compose logs api --tail 200
2. Search the Gitea issues
3. Review the Deployment guide for production-specific issues
4. File a new issue with your logs and .env (redact passwords)