---
title: Troubleshooting
description: Solutions for common errors, CORS issues, database problems, and tunnel debugging.
icon: material/bug
tags:
  - troubleshooting
  - operator
search:
  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`:

```bash
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:**

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

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

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

```bash
# 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](https://gitea.bnkops.com/admin/changemaker.lite/issues)
3. Review the [Deployment guide](../deployment/index.md) for production-specific issues
4. File a new issue with your logs and `.env` (redact passwords)
