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)