# Troubleshooting Guide

This guide covers common issues and their solutions for the Torrent Gateway native installation.

## Service Issues

#### Gateway Won't Start

**Symptoms:** Service exits immediately or health checks fail

**Diagnostic Steps:**
```bash
# Check service status
sudo systemctl status torrent-gateway

# Check detailed logs
sudo journalctl -u torrent-gateway -f

# Check database file
ls -la /opt/torrent-gateway/data/metadata.db

# Test database connection
sqlite3 /opt/torrent-gateway/data/metadata.db "SELECT COUNT(*) FROM files;"
```

**Solutions:**
1. **Fix permissions:**
   ```bash
   sudo chown -R torrent-gateway:torrent-gateway /opt/torrent-gateway/data
   ```

2. **Check disk space:**
   ```bash
   df -h /opt/torrent-gateway/
   ```

3. **Reset database (last resort):**
   ```bash
   sudo systemctl stop torrent-gateway
   sudo mv /opt/torrent-gateway/data/metadata.db /opt/torrent-gateway/data/metadata.db.backup
   sudo systemctl start torrent-gateway
   ```

#### Cache Performance Issues

**Symptoms:** High memory usage, slow response times

**Solutions:**
The gateway uses an in-memory LRU cache (no Redis required):
```bash
# Check memory usage
free -h
sudo systemctl status torrent-gateway

# Restart service to clear cache
sudo systemctl restart torrent-gateway
```

### Performance Issues

#### High CPU Usage

**Diagnostic:**
```bash
# Check service resources
systemctl status torrent-gateway
htop

# Check system resources
top
```

**Solutions:**
1. **Check for resource leaks:**
   ```bash
   sudo journalctl -u torrent-gateway | grep -i "memory\|leak"
   ```

2. **Optimize database:**
   ```bash
   /opt/torrent-gateway/scripts/migrate.sh  # Runs VACUUM and ANALYZE
   ```

3. **Add resource limits:**
   Edit systemd service limits in `/etc/systemd/system/torrent-gateway.service`

#### High Memory Usage

**Diagnostic:**
```bash
# Check memory usage
free -h
ps aux | grep gateway

# Check for memory leaks in logs
sudo journalctl -u torrent-gateway | grep -i "memory\|leak\|oom"
```

**Solutions:**
1. **Restart service:**
   ```bash
   sudo systemctl restart torrent-gateway
   ```

2. **Implement stricter memory limits:**
   ```ini
   # In /etc/systemd/system/torrent-gateway.service
   [Service]
   MemoryMax=1G
   ```

#### Slow File Operations

**Common Causes:**
- Disk I/O bottleneck
- Database fragmentation
- Too many concurrent operations

**Solutions:**
```bash
# Check disk I/O
iostat -x 1

# Optimize database
sqlite3 /opt/torrent-gateway/data/metadata.db "VACUUM; ANALYZE;"

# Check file system
df -h
find /opt/torrent-gateway/data -name "*.tmp" -delete
```

## Database Issues

#### Database Locked Errors

**Symptoms:** "database is locked" errors

**Solutions:**
```bash
# Find processes using database
lsof /opt/torrent-gateway/data/metadata.db

# Stop service and clean up (if safe)
sudo systemctl stop torrent-gateway
rm -f /opt/torrent-gateway/data/metadata.db-wal /opt/torrent-gateway/data/metadata.db-shm
sudo systemctl start torrent-gateway
```

#### Database Corruption

**Symptoms:** SQL errors, integrity check failures

**Diagnostic:**
```bash
# Check database integrity
sqlite3 /opt/torrent-gateway/data/metadata.db "PRAGMA integrity_check;"
```

**Solutions:**
1. **Try repair:**
   ```bash
   sudo systemctl stop torrent-gateway
   sqlite3 /opt/torrent-gateway/data/metadata.db ".recover" > /tmp/recovered.sql
   sqlite3 /opt/torrent-gateway/data/metadata_new.db < /tmp/recovered.sql
   ```

2. **Restore from backup:**
   ```bash
   sudo /opt/torrent-gateway/scripts/restore.sh BACKUP_TIMESTAMP
   ```

### Storage Issues

#### Disk Space Full

**Diagnostic:**
```bash
# Check disk usage
df -h /opt/torrent-gateway/
du -sh /opt/torrent-gateway/data/*
```

**Solutions:**
```bash
# Run cleanup script
sudo /opt/torrent-gateway/scripts/cleanup.sh

# Manual cleanup
find /opt/torrent-gateway/data/chunks -type f -mtime +30 -delete
find /opt/torrent-gateway/logs -name "*.log" -mtime +7 -delete
```

#### File Upload Failures

**Common Issues:**
- Nginx client_max_body_size too small
- Disk space insufficient
- Permissions problems

**Solutions:**
```bash
# Check nginx configuration
sudo nginx -t
sudo systemctl reload nginx

# Check upload directory permissions
ls -la /opt/torrent-gateway/data/

# Increase nginx limits
sudo vim /etc/nginx/sites-available/torrent-gateway
# Update: client_max_body_size 50G;
```

## Network Issues

#### Connection Timeouts

**Symptoms:** API requests timeout, health checks fail

**Diagnostic:**
```bash
# Test local connectivity
curl -v http://localhost:9877/api/health

# Check network configuration
ss -tulpn | grep 9877
```

**Solutions:**
```bash
# Restart nginx
sudo systemctl restart nginx

# Check firewall
sudo ufw status

# Increase timeouts
curl --connect-timeout 30 --max-time 60 http://localhost:9877/api/health
```

#### Port Binding Issues

**Symptoms:** "Port already in use" errors

**Diagnostic:**
```bash
# Check what's using the port
sudo lsof -i :9877
sudo netstat -tulpn | grep 9877
```

**Solutions:**
```bash
# Kill conflicting process
sudo kill $(sudo lsof -t -i:9877)

# Or change port in configuration
sudo vim /opt/torrent-gateway/configs/config.yaml
```

### SSL/HTTPS Issues

#### Certificate Errors

**Symptoms:** SSL warnings, certificate expired

**Solutions:**
```bash
# Check certificate status
sudo certbot certificates

# Renew certificates
sudo certbot renew

# Test renewal
sudo certbot renew --dry-run
```

#### Mixed Content Warnings

**Causes:** HTTP resources loaded on HTTPS page

**Solutions:**
```bash
# Check nginx configuration
sudo vim /etc/nginx/sites-available/torrent-gateway
# Ensure all proxy_set_header X-Forwarded-Proto $scheme;
```

### Monitoring Issues

#### Prometheus Not Scraping

**Diagnostic:**
```bash
# Check Prometheus service
sudo systemctl status prometheus

# Check metrics endpoint
curl -s http://localhost:9877/metrics
```

**Solutions:**
```bash
# Restart Prometheus
sudo systemctl restart prometheus

# Check configuration
sudo vim /opt/prometheus/prometheus.yml
```

#### Grafana Dashboard Issues

**Common Problems:**
1. **No data in dashboards:**
   - Check Prometheus data source configuration
   - Verify metrics are being collected: `curl http://localhost:9877/metrics`

2. **Dashboard import errors:**
   - Verify dashboard version compatibility

## Video Transcoding Issues

#### FFmpeg Errors

**Symptoms:** Transcoding fails, codec errors

**Diagnostic:**
```bash
# Check FFmpeg installation
ffmpeg -version

# Check logs for transcoding errors
sudo journalctl -u torrent-gateway | grep -i "transcode\|ffmpeg"
```

**Solutions:**
```bash
# Install/update FFmpeg
sudo apt update
sudo apt install -y ffmpeg

# Check disk space for temp files
df -h /opt/torrent-gateway/data/transcoded/
```

## Log Analysis

#### Finding Specific Errors

```bash
# Gateway application logs
sudo journalctl -u torrent-gateway --since "1 hour ago"

# System logs with timestamps
sudo journalctl --since "1 hour ago" | grep gateway

# Follow logs in real-time
sudo journalctl -u torrent-gateway -f
```

#### Log Rotation Issues

```bash
# Check log sizes
sudo du -sh /opt/torrent-gateway/logs/*

# Manually rotate logs
sudo logrotate -f /etc/logrotate.d/torrent-gateway
```

## Emergency Procedures

### Complete Service Failure

1. **Stop all services:**
   ```bash
   sudo systemctl stop torrent-gateway nginx redis-server
   ```

2. **Check system resources:**
   ```bash
   df -h
   free -h
   top
   ```

3. **Restore from backup:**
   ```bash
   sudo /opt/torrent-gateway/scripts/restore.sh LATEST_BACKUP
   ```

4. **Restart services:**
   ```bash
   sudo systemctl start redis-server nginx torrent-gateway
   ```

### Data Recovery

```bash
# Create emergency backup
sudo tar -czf /tmp/gateway_emergency_$(date +%Y%m%d_%H%M%S).tar.gz /opt/torrent-gateway/data/

# Check database
sqlite3 /opt/torrent-gateway/data/metadata.db ".schema"
```

## Diagnostic Information Collection

### Log Collection

Before reporting issues, collect relevant logs:

```bash
# Create diagnostics package
mkdir -p diagnostics
sudo journalctl -u torrent-gateway --since "1 day ago" > diagnostics/service_logs.txt
sudo /opt/torrent-gateway/scripts/health_check.sh > diagnostics/health_check.txt 2>&1
cp /opt/torrent-gateway/data/metadata.db diagnostics/ 2>/dev/null || echo "Database not accessible"
tar -czf diagnostics_$(date +%Y%m%d_%H%M%S).tar.gz diagnostics/
```

### Health Check Output

Always include health check results:
```bash
sudo /opt/torrent-gateway/scripts/health_check.sh | tee health_status.txt
```

### System Information

```bash
# Collect system info
echo "System: $(uname -a)" > system_info.txt
echo "Memory: $(free -h)" >> system_info.txt
echo "Disk: $(df -h)" >> system_info.txt
echo "FFmpeg: $(ffmpeg -version 2>/dev/null | head -1 || echo 'Not installed')" >> system_info.txt
echo "Go version: $(go version 2>/dev/null || echo 'Not installed')" >> system_info.txt
```

## Getting Help

### Information to Include

When reporting issues, always include:
1. System information (OS, version, architecture)
2. Installation method and version
3. Error messages and logs
4. Steps to reproduce
5. Expected vs actual behavior

### Log Locations

- **Application logs:** `sudo journalctl -u torrent-gateway`
- **Nginx logs:** `/var/log/nginx/error.log`
- **System logs:** `/var/log/syslog`
- **Health check logs:** `/var/log/torrent-gateway-health.log`

### Useful Commands

```bash
# Full system status
sudo /opt/torrent-gateway/scripts/health_check.sh

# Service overview
sudo systemctl status torrent-gateway nginx redis-server

# Resource usage
htop
df -h
free -h
```