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
```

### SSL Certificate Errors

**Error:** Browser shows certificate warnings

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

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