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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   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 instructions
• Quick Start - Deployment steps
• Testing Guide - Verification procedures
• Security Setup - Security configuration
• Deployment Guide - Production deployment