coop/docs/TROUBLESHOOTING.md

CoopCredits Troubleshooting Guide

Installation Warnings

NPM Deprecation Warnings

When running npm install, you may see warnings like:

npm WARN deprecated inflight@1.0.6: This module is not supported...
npm WARN deprecated glob@7.2.0: Old versions of glob are not supported...
npm WARN deprecated @walletconnect/sign-client@2.19.0: ...

These are safe to ignore. These warnings come from:

• Transitive dependencies (dependencies of dependencies)
• Solana wallet adapter packages that haven't updated yet
• Legacy packages still used by the Anchor framework

Critical fix applied:

• ✅ Next.js updated from 14.0.4 to 14.2.15 (security vulnerability patched)

What you can do:

# The warnings don't affect functionality
# To suppress them during install:
npm install --silent

# Or use --legacy-peer-deps if needed:
npm install --legacy-peer-deps

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

Solana Program Build Fails

Error: anchor build fails with Rust errors

Solution:

# Update Rust
cd anchor-program
rustup update

# Rebuild
anchor clean
anchor build

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 Nginx logs:

   tail -f docker/nginx/logs/access.log
   

4. Test webhook manually:

   curl -X POST https://coop.hobokenchicken.com/webhooks/tautulli \
     -H "Content-Type: application/json" \
     -d '{"test": true}'
   

Cannot Reach Local Services (172.20.1.x)

Error: Backend cannot connect to Plex/Tautulli/Overseer

Solution:

# Test connectivity from backend container
docker exec coop-backend ping 172.20.1.255

# Check Docker network
docker network ls
docker network inspect coop-credits_coop-external

# Verify firewall rules
sudo ufw status

Wallet Creation Fails

Error: Failed to create wallet or Solana errors

Solution:

# Check Solana configuration
solana config get

# Ensure you're on devnet
solana config set --url devnet

# Check balance
solana balance

# Request airdrop if needed
solana airdrop 2

SSL Certificate Errors

Error: Browser shows certificate warnings

Solution:

# Check certificate
openssl s_client -connect coop.hobokenchicken.com:443

# Renew Let's Encrypt
docker-compose -f docker-compose.prod.yml run --rm certbot renew

# Or use self-signed for testing:
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout docker/nginx/ssl/key.pem \
  -out docker/nginx/ssl/cert.pem \
  -subj '/CN=coop.hobokenchicken.com'

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 includes your domain
3. Restart backend after changes

High Memory Usage

Symptom: Server slows down or OOM errors

Solution:

# Check what's using memory
docker stats

# Restart services
docker-compose -f docker-compose.prod.yml restart

# Increase swap if needed
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Docker Build Issues

Backend Build Fails: Cannot redeclare block-scoped variable

Error: error TS2451: Cannot redeclare block-scoped variable 'signature'

Solution: Fixed in source. If you see this, pull the latest code.

Backend: Prisma Client could not locate Query Engine

Error: PrismaClientInitializationError: Prisma Client could not locate the Query Engine

Solution:

# Regenerate Prisma client with correct binary target
cd backend
npx prisma generate

# Rebuild backend container
docker-compose up -d --build backend

Frontend Build Fails: Module not found

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

Solution: Ensure tsconfig.json has correct paths:

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

Frontend: Prerender Error on /login

Error: Error occurred prerendering page "/login"

Solution: This was caused by zustand persist middleware accessing localStorage during SSR. Fixed by wrapping providers with dynamic import ssr: false.

Frontend: Cannot find module 'next-themes'

Error: Module not found: Can't resolve 'next-themes'

Solution:

cd frontend
npm install next-themes

Nginx: SSL Certificate Error

Error: cannot load certificate "/etc/nginx/ssl/cert.pem"

Solution:

mkdir -p docker/nginx/ssl
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout docker/nginx/ssl/key.pem \
  -out docker/nginx/ssl/cert.pem \
  -subj "/CN=coop.hobokenchicken.com"

Docker Compose: Public Directory Not Found

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

Solution:

mkdir -p frontend/public
touch frontend/public/.gitkeep

Getting Help

1. Check health status:

   ./deployment/health-check.sh
   

2. View all logs:

   docker-compose -f docker-compose.prod.yml logs -f
   

3. Check specific service:

   docker-compose -f docker-compose.prod.yml logs -f backend
   

4. Verify environment:

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