# CoopCredits Troubleshooting Guide

## Common Issues

### Database Connection Failed

**Error:** `Can't reach database server at localhost:5432`

**Solution:**
```bash
# Start PostgreSQL
docker-compose up -d postgres

# Wait for it to be ready
sleep 5

# Verify
docker-compose exec postgres pg_isready -U coop
```

### Webhooks Not Receiving

**Error:** Tautulli/Overseer webhooks not triggering

**Solution:**
1. Verify CoopCredits backend is accessible:
   ```bash
   curl https://coop.hobokenchicken.com/health
   ```

2. Check webhook URL in Tautulli/Overseer settings

3. Check Caddy routes `/webhooks/*` to backend port 3002

4. Check backend logs:
   ```bash
   docker logs --tail 50 coop-backend
   ```

5. Test webhook manually:
   ```bash
   curl -X POST https://coop.hobokenchicken.com/webhooks/tautulli \
     -H "Content-Type: application/json" \
     -d '{"action":"watched","user_id":"1","rating_key":"1","session_key":"1","media_type":"movie","title":"Test","started":1,"stopped":3601,"percent_complete":90}'
   ```

### Cannot Reach Local Services (172.20.1.x)

**Error:** Backend cannot connect to Plex/Tautulli/Overseer

**Solution:**
```bash
# Verify backend is in host network mode
docker inspect coop-backend | grep NetworkMode
# Should show: "host"

# Test connectivity from host
ping 172.20.1.255

# Check backend logs
docker logs --tail 50 coop-backend

# Verify env vars
docker exec coop-backend env | grep TAUTULLI
docker exec coop-backend env | grep OVERSEER
```

> Backend must use `network_mode: host` to reach `172.20.1.x` subnet. Docker bridge networking cannot route to this subnet.

### Ko-fi Webhook Not Working

**Error:** Payments not crediting users

**Solution:**
1. Verify `KOFI_VERIFICATION_TOKEN` env var is set in backend container:
   ```bash
   docker exec coop-backend env | grep KOFI
   ```

2. Check Ko-fi webhook settings — URL should be:
   ```
   https://coop.hobokenchicken.com/webhooks/kofi
   ```

3. Check backend logs for verification token mismatch

4. Check admin **Donations** tab to see if payments arrive as UNCLAIMED (email mismatch)

### BigInt JSON Serialization Error

**Error:** `Do not know how to serialize a BigInt`

**Solution:** This is fixed in `backend/src/index.ts` with:
```typescript
(BigInt.prototype as any).toJSON = function () {
  return this.toString();
};
```

If you still see it, ensure the patch is loaded before any route handlers.

### CORS Errors in Browser

**Error:** `Access-Control-Allow-Origin` errors

**Solution:**
1. Check `FRONTEND_URL` in backend `.env` matches your actual URL
2. Verify CORS origins include your domain in `backend/src/index.ts`
3. Restart backend after changes

### Rate Limiting (429 Too Many Requests)

**Error:** Dashboard shows "Slow down, chicken!" or fails to load

**Solution:**
- Rate limit is 1000 requests per 15 minutes per IP
- If you hit it, wait a few minutes
- The dashboard makes several parallel calls on load — this is normal

### Frontend Build Fails: Module not found

**Error:** `Module not found: Can't resolve '@/components/ui/...'`

**Solution:** Ensure `tsconfig.json` has correct paths:
```json
"paths": {
  "@/*": ["./src/*"]
}
```

### Docker Build: Public Directory Not Found

**Error:** `failed to calculate checksum: "/app/frontend/public": not found`

**Solution:**
```bash
mkdir -p frontend/public
touch frontend/public/.gitkeep
```

### Request Stuck on PENDING

**Error:** Request never updates from PENDING status

**Solution:**
1. Check Overseer webhook is configured correctly
2. In admin dashboard, go to **The Feed Queue** tab and click **SYNC**
3. Or manually sync from dashboard's Requests tab
4. Check backend logs for Overseer API errors

### Disk Space Not Updating

**Error:** Silo bar shows old values after downloading large files

**Solution:**
- Disk space is cached for 30 seconds
- Wait 30 seconds and refresh
- The bar updates automatically on dashboard load

## Getting Help

1. View all logs:
   ```bash
   docker-compose logs -f
   ```

2. Check specific service:
   ```bash
   docker-compose logs -f backend
   docker-compose logs -f frontend
   ```

3. Verify environment:
   ```bash
   # Check all required env vars are set
   grep -E '^\w+=' .env | wc -l
   ```

4. Check database:
   ```bash
   docker exec coop-postgres psql -U coop -d coop_credits -c "SELECT COUNT(*) FROM users;"
   ```