Skip to content

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

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)