coop/docs/TROUBLESHOOTING.md

CoopCredits Troubleshooting Guide

Common Issues

Database Connection Failed

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

Solution:

# 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:

   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:

   docker logs --tail 50 coop-backend
   

5. Test webhook manually:

   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:

# 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:

   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:

(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:

"paths": {
  "@/*": ["./src/*"]
}

Docker Build: Public Directory Not Found

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

Solution:

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:

   docker-compose logs -f
   

2. Check specific service:

   docker-compose logs -f backend
   docker-compose logs -f frontend
   

3. Verify environment:

   # Check all required env vars are set
   grep -E '^\w+=' .env | wc -l
   

4. Check database:

   docker exec coop-postgres psql -U coop -d coop_credits -c "SELECT COUNT(*) FROM users;"