Troubleshooting¶

Common issues and solutions.

Service Issues¶

Service Won't Start¶

Symptoms: systemctl start hangs or fails

Check logs:

sudo journalctl -u {slug}-api -f
sudo journalctl -u {slug}-frontend -f

Common causes:

Port in use:
```
lsof -i :32310
kill -9 {pid}
```

Missing dependencies:

cd /path/to/{slug}
source venv/bin/activate
pip install -r requirements.txt

Database locked:

# Find processes using the database
lsof /path/to/{slug}/db/pocket.db

Service Crashes Repeatedly¶

Check for:

Memory issues: free -h
Disk space: df -h
Python errors in logs

Solution:

# Restart with fresh state
sudo systemctl stop {slug}-api {slug}-frontend
rm -f /path/to/{slug}/.pid*
sudo systemctl start {slug}-api {slug}-frontend

Database Issues¶

Database Locked¶

# Find what's locking it
lsof /path/to/pocket.db

# Force unlock (caution!)
cp pocket.db pocket.db.backup
sqlite3 pocket.db "PRAGMA integrity_check;"

Migration Fails¶

# Run migrations manually
cd /path/to/{slug}
source venv/bin/activate
python scripts/create_schema.py
python scripts/add_person_columns.py
# etc.

Corrupted Database¶

# Restore from backup
cp pocket.db.backup_TIMESTAMP pocket.db

# Or recover
sqlite3 pocket.db ".recover" | sqlite3 pocket_recovered.db

Network Issues¶

Can't Connect to Tenant¶

Check:

Service running: systemctl status {slug}-api
Port accessible: curl http://localhost:{port}/docs
Nginx configured: nginx -t
Firewall rules: ufw status

GitHub Clone Fails¶

# Test SSH access
ssh -T git@github.com

# Fix permissions
chmod 600 ~/.ssh/id_ed25519
eval $(ssh-agent)
ssh-add ~/.ssh/id_ed25519

Upgrade Issues¶

Git Fetch Fails¶

# Error: couldn't find remote ref refs/heads/master

# Fix: Update fetch refspec
cd /path/to/{slug}
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch origin

Version Check Shows Wrong Status¶

Known issue: upgrade_available: true even when on latest version.

This is a cosmetic issue (Issue #25) - the comparison uses commits instead of version tags.

Authentication Issues¶

Token Expired¶

# Get new token
curl -s -X POST http://localhost:32201/api/auth/login \
  -d "username=admin&password=admin123"

Wrong Password¶

# Reset password (Python)
cd /path/to/cbtenant
source venv/bin/activate
python3 << 'EOF'
import bcrypt
from db.database import SessionLocal
from db.models import User

db = SessionLocal()
user = db.query(User).filter(User.username == "admin").first()
user.password_hash = bcrypt.hashpw(b'admin123', bcrypt.gensalt()).decode('utf-8')
db.commit()
print("Password reset!")
EOF

Performance Issues¶

Slow API Response¶