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

### Solana Program Build Fails

**Error:** `anchor build` fails with Rust errors

**Solution:**
```bash
# 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:
   ```bash
   curl https://coop.hobokenchicken.com/health
   ```

2. Check webhook URL in Tautulli/Overseer settings

3. Check Nginx logs:
   ```bash
   tail -f docker/nginx/logs/access.log
   ```

4. Test webhook manually:
   ```bash
   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:**
```bash
# 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:**
```bash
# 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
```

### 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:**
```bash
# 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:**
```bash
# 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:
```json
"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:** 
```bash
cd frontend
npm install next-themes
```

### Docker Compose: Public Directory Not Found

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

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

## Getting Help

1. Check health status:
   ```bash
   ./deployment/health-check.sh
   ```

2. View all logs:
   ```bash
   docker-compose -f docker-compose.prod.yml logs -f
   ```

3. Check specific service:
   ```bash
   docker-compose -f docker-compose.prod.yml logs -f backend
   ```

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