campaign_connector/docs/guides/troubleshooting.md

# Troubleshooting Guide

Common issues and solutions for SMS Campaign Manager.

## Application Issues

### Docker Container Won't Start

**Symptoms**: Container exits immediately or won't start

**Solutions**:
```bash
# Check logs for errors
docker compose logs sms-campaign

# Verify environment variables are set
cat .env | grep -E "(API_KEY|SECRET_KEY|PHONE_IP)"

# Rebuild the container
docker compose down
docker compose build --no-cache
docker compose up -d
```

### Database Errors

**Symptoms**: "database is locked" or "unable to open database file"

**Solutions**:
```bash
# Stop all containers
docker compose down

# Check database file permissions
ls -la data/campaign.db

# Restart
docker compose up -d

# If corrupted, reset database (WARNING: deletes all data)
rm data/campaign.db
docker compose restart
```

### Can't Access Web Dashboard

**Symptoms**: Connection refused or 404 errors

**Solutions**:
```bash
# Verify container is running
docker compose ps

# Check if port 5000 is exposed
docker compose port sms-campaign 5000

# Check firewall rules
sudo ufw status | grep 5000

# Try localhost specifically
curl http://127.0.0.1:5000/health
```

## Authentication Issues

### API Key Not Working

**Symptoms**: "Authentication required" or "Invalid API key"

**Solutions**:
```bash
# Verify keys are loaded in container
docker compose exec sms-campaign env | grep API_KEY

# Check .env file format (no spaces around =)
cat .env | grep API_KEY

# Restart to reload environment
docker compose restart

# Test with curl
curl -H "X-API-Key: YOUR_KEY" http://localhost:5000/api/campaign/list
```

### Can't Log In to Web Dashboard

**Symptoms**: "Invalid username or password"

**Solutions**:
```bash
# List existing users
python3 manage_users.py
# Select option 2

# Reset admin password via .env
nano .env
# Update ADMIN_PASSWORD
docker compose restart

# Create new user if needed
python3 manage_users.py
# Select option 1
```

### Session Expires Immediately

**Symptoms**: Logged out after every page refresh

**Solutions**:
```bash
# Check browser cookies are enabled
# Clear browser cache and cookies for localhost
# Check session configuration in logs
docker compose logs | grep -i session

# Verify SECRET_KEY is set in .env
grep SECRET_KEY .env
```

## Android/Termux Issues

### Can't Connect to Android Device

**Symptoms**: Connection timeouts, "device not found"

**Solutions**:
```bash
# Verify Tailscale is running on both devices
tailscale status

# Ping Android device
ping YOUR_ANDROID_TAILSCALE_IP

# Test SSH connection
ssh -p 8022 android-dev@YOUR_ANDROID_IP "whoami"

# Check PHONE_IP in .env matches Android
grep PHONE_IP .env
```

### Termux API Server Not Responding

**Symptoms**: `/health` endpoint returns 404 or times out

**Solutions**:
```bash
# SSH to Android
ssh -p 8022 android-dev@YOUR_ANDROID_IP

# Check if service is running
ps aux | grep termux-sms-api-server

# View service logs
tail -f ~/logs/sms-api.log

# Restart service
pkill -f termux-sms-api-server.py
~/bin/start-sms-api.sh

# Or redeploy everything
exit
./scripts/deploy-android.sh
```

### SMS Not Sending

**Symptoms**: Messages fail to send, stuck in queue

**Solutions**:
```bash
# Check Termux:API permissions on Android
# Settings → Apps → Termux:API → Permissions → SMS (Allow)

# Test Termux API directly
ssh -p 8022 android-dev@YOUR_ANDROID_IP
termux-sms-list -l 1  # Should list recent SMS

# Check API server logs
tail -20 ~/logs/sms-api.log

# Verify API key is set on Android
grep SMS_API_SECRET ~/projects/sms-campaign-manager/.env

# Test SMS sending
curl -X POST http://YOUR_ANDROID_IP:5001/api/sms/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_TERMUX_API_KEY" \
  -d '{"phone":"YOUR_NUMBER","message":"Test"}'
```

## Network Issues

### Tailscale Connection Problems

**Symptoms**: Can't reach devices over Tailscale

**Solutions**:
```bash
# Check Tailscale status on Ubuntu
tailscale status
tailscale ping YOUR_ANDROID_IP

# Restart Tailscale
sudo systemctl restart tailscaled

# On Android (in Termux)
# Open Tailscale app and reconnect

# Verify IPs haven't changed
tailscale ip -4
```

### SSH Connection Refused

**Symptoms**: Can't SSH to Android device

**Solutions**:
```bash
# On Android (in Termux)
# Start SSH server
sshd

# Check if running
ps aux | grep sshd

# Set password if not set
passwd

# Check SSH port
cat $PREFIX/etc/ssh/sshd_config | grep Port
```

## Performance Issues

### Slow SMS Sending

**Symptoms**: Messages take too long to send

**Solutions**:
```bash
# Check retry configuration in .env
grep SMS_MAX_RETRIES .env
grep DEFAULT_DELAY_SECONDS .env

# Reduce delays for faster sending
# Edit .env:
# DEFAULT_DELAY_SECONDS=1
# SMS_RETRY_BASE_DELAY=1

# Restart
docker compose restart
```

### High CPU Usage

**Symptoms**: Container using excessive CPU

**Solutions**:
```bash
# Check container resource usage
docker stats sms-campaign

# View active processes
docker compose exec sms-campaign ps aux

# Check for infinite loops in logs
docker compose logs --tail 100 sms-campaign

# Restart container
docker compose restart
```

## Data Issues

### Lost Campaign Data

**Symptoms**: Campaigns or contacts disappeared

**Solutions**:
```bash
# Check if database file exists
ls -lh data/campaign.db

# Restore from backup (if you have one)
cp data/campaign.db.backup data/campaign.db
docker compose restart

# Export data for backup
sqlite3 data/campaign.db ".dump" > backup.sql
```

### CSV Upload Fails

**Symptoms**: File upload errors or parsing failures

**Solutions**:
```bash
# Check file format
head -5 your_file.csv

# Ensure CSV has proper headers
# Required: phone, name (optional: message, email, etc.)

# Check file size
ls -lh your_file.csv

# Verify upload directory permissions
ls -ld uploads/
```

## Getting Help

If issues persist:

1. **Check logs**: `docker compose logs -f sms-campaign`
2. **Verify environment**: `docker compose exec sms-campaign env`
3. **Test connectivity**: `curl http://localhost:5000/health`
4. **Review configuration**: Check `.env` file for typos
5. **Restart everything**:
   ```bash
   docker compose down
   ./scripts/deploy-android.sh
   docker compose up -d
   ```

## Reporting Issues

When reporting issues, include:
- Error messages from logs
- Steps to reproduce
- Environment details (OS, Docker version)
- Configuration (sanitized `.env` without secrets)

## Related Documentation

- [Installation Guide](../setup/installation.md) - Setup instructions
- [Quick Start](../setup/quick-start.md) - Deployment steps
- [Testing Guide](testing.md) - Verification procedures
- [Security Setup](../security/security-setup.md) - Security configuration
- [Deployment Guide](../deployment/deployment-guide.md) - Production deployment