chitfund/TROUBLESHOOTING.md

# 🔧 LuckyChit Troubleshooting Guide

Quick fixes for common issues.

---

## 🚨 Quick Diagnostics

```bash
cd /home/luckychit/apps/chitfund
./scripts/diagnose.sh
```

This shows exactly what's wrong!

---

## Common Issues

### 🔴 502 Bad Gateway Error

**Symptom**: Site shows "502 Bad Gateway"  
**Cause**: PM2 processes are down or nginx can't reach backend

**Fix**:
```bash
# Check PM2
pm2 status

# If processes are down
pm2 restart all

# If processes don't exist
cd /home/luckychit/apps/chitfund
./scripts/fix-502.sh

# Test
curl http://localhost:3000/health
curl http://localhost:8080
```

---

### 🔴 Changes Not Showing (Cache Issue)

**Symptom**: Deployed code but seeing old version  
**Cause**: Multiple cache layers (browser, service worker, nginx, Cloudflare)

**Fix**:
```bash
# 1. Clear browser service worker
# F12 → Application → Service Workers → Unregister
# Then: Ctrl + Shift + R (hard refresh)

# 2. Or test in incognito
# Ctrl + Shift + N (no cache at all)

# 3. Force rebuild on server
cd /home/luckychit/apps/chitfund
./scripts/deploy.sh --force

# 4. Clear nginx cache (if using separate proxy)
ssh root@<nginx-ip>
sudo rm -rf /var/cache/nginx/*
sudo systemctl reload nginx

# 5. Purge Cloudflare cache
# Dashboard → Caching → Purge Everything
```

---

### 🔴 PM2 Not Running After Reboot

**Symptom**: Server restarted, apps not running  
**Cause**: PM2 auto-start not configured

**Fix**:
```bash
# Restore processes
pm2 resurrect

# Or setup auto-start
pm2 startup systemd -u luckychit --hp /home/luckychit
# Run the command it outputs
pm2 save
```

---

### 🔴 "invalid ELF header" Error

**Symptom**: Backend crashes with bcrypt error  
**Cause**: node_modules installed on Windows, running on Linux

**Fix**:
```bash
cd /home/luckychit/apps/chitfund/backend
rm -rf node_modules package-lock.json
npm install
pm2 restart luckychit-api
```

---

### 🔴 Database Connection Error

**Symptom**: Backend logs show "connection refused"  
**Cause**: PostgreSQL not running or wrong credentials

**Fix**:
```bash
# Check PostgreSQL
sudo systemctl status postgresql

# If not running
sudo systemctl start postgresql

# Test connection
psql -U luckychit -h localhost -d luckychit

# Check .env credentials
cd /home/luckychit/apps/chitfund/backend
cat .env | grep DB_
```

---

### 🔴 Port Already in Use

**Symptom**: "Port 3000 already in use"  
**Cause**: Old process still running

**Fix**:
```bash
# Find process
netstat -tulpn | grep 3000

# Kill process
kill -9 <PID>

# Or restart PM2
pm2 restart luckychit-api
```

---

### 🔴 Out of Memory

**Symptom**: PM2 processes keep crashing  
**Cause**: Server out of RAM

**Fix**:
```bash
# Check memory
free -h

# Check PM2 memory usage
pm2 monit

# Restart to free memory
pm2 restart all

# Or reboot server
sudo reboot
```

---

### 🔴 Frontend Won't Build

**Symptom**: `flutter build web` fails  
**Cause**: Corrupted cache or missing dependencies

**Fix**:
```bash
cd /home/luckychit/apps/chitfund/luckychit
flutter clean
rm -rf .dart_tool build
flutter pub get
flutter build web --release --pwa-strategy=none
```

---

### 🔴 Service Worker Errors in Browser

**Symptom**: Console shows "Loading from existing service worker" + errors  
**Cause**: Old service worker serving stale code

**Fix**:
```bash
# In browser:
# 1. Press F12
# 2. Application tab → Service Workers
# 3. Click "Unregister" for all
# 4. Application tab → Clear storage → Clear site data
# 5. Close DevTools
# 6. Hard refresh: Ctrl + Shift + R

# Already fixed in code - rebuilds now disable service worker
```

---

### 🔴 Nginx Not Forwarding Requests

**Symptom**: 502 only on domain, direct IP works  
**Cause**: Nginx config issue or cache

**Fix**:
```bash
# SSH to nginx proxy LXC
ssh root@<nginx-ip>

# Test backend connectivity
curl http://192.168.8.148:3000/health
curl http://192.168.8.148:8080

# Check nginx config
sudo nginx -t

# Clear cache
sudo rm -rf /var/cache/nginx/*

# Reload nginx
sudo systemctl reload nginx

# Check logs
sudo tail -f /var/log/nginx/error.log
```

---

### 🔴 Firewall Blocking Access

**Symptom**: Can't access from outside server  
**Cause**: Firewall rules

**Fix**:
```bash
# Check firewall
sudo ufw status

# Allow ports
sudo ufw allow 3000/tcp
sudo ufw allow 8080/tcp
sudo ufw reload

# Test
curl http://192.168.8.148:3000/health
```

---

## 🔍 Diagnostic Commands

```bash
# Check everything
./scripts/diagnose.sh

# PM2 status
pm2 status
pm2 logs --lines 50

# Test connectivity
curl http://localhost:3000/health    # Backend
curl http://localhost:8080            # Frontend

# Check disk space
df -h

# Check memory
free -h

# Check ports
netstat -tulpn | grep -E '(3000|8080)'

# Check database
psql -U luckychit -h localhost -d luckychit
```

---

## 🚀 Emergency Recovery

### Complete Reset
```bash
# Stop everything
pm2 kill

# Restart from scratch
cd /home/luckychit/apps/chitfund

# Backend
cd backend
pm2 start src/server.js --name luckychit-api

# Frontend
cd ../luckychit
pm2 serve build/web 8080 --name luckychit-frontend --spa

# Save
pm2 save

# Verify
pm2 status
```

### Nuclear Option (Full Rebuild)
```bash
cd /home/luckychit/apps/chitfund
./scripts/deploy.sh --force
```

---

## 📞 Still Stuck?

1. **Run diagnostics**: `./scripts/diagnose.sh`
2. **Check PM2 logs**: `pm2 logs --lines 100`
3. **Try in incognito**: Rules out browser cache
4. **Restart everything**: `pm2 restart all`
5. **Check all docs**: [DEPLOYMENT.md](DEPLOYMENT.md)

---

## 🎯 Prevention Tips

1. **Always test locally** before deploying
2. **Use deployment script** (handles caching automatically)
3. **Check logs after deploy**: `pm2 logs --lines 20`
4. **Test in incognito** first (no cache)
5. **Backup database** before major changes
6. **Monitor PM2**: `pm2 monit`

---

**Most issues are cache-related. When in doubt, clear all caches and rebuild!**