torrent-gateway/docs/troubleshooting.md

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:

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

   sudo chown -R torrent-gateway:torrent-gateway /opt/torrent-gateway/data
   

2. Check disk space:

   df -h /opt/torrent-gateway/
   

3. Reset database (last resort):

   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
   

Redis Connection Issues

Symptoms: Gateway logs show Redis connection errors

Solutions:

# Check Redis service
sudo systemctl status redis-server

# Test Redis connection
redis-cli ping

# Restart Redis
sudo systemctl restart redis-server

Performance Issues

High CPU Usage

Diagnostic:

# Check service resources
systemctl status torrent-gateway
htop

# Check system resources
top

Solutions:

1. Check for resource leaks:

   sudo journalctl -u torrent-gateway | grep -i "memory\|leak"
   

2. Optimize database:

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

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

   sudo systemctl restart torrent-gateway
   

2. Implement stricter memory limits:

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

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

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

# Check database integrity
sqlite3 /opt/torrent-gateway/data/metadata.db "PRAGMA integrity_check;"

Solutions:

1. Try repair:

   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:

   sudo /opt/torrent-gateway/scripts/restore.sh BACKUP_TIMESTAMP
   

Storage Issues

Disk Space Full

Diagnostic:

# Check disk usage
df -h /opt/torrent-gateway/
du -sh /opt/torrent-gateway/data/*

Solutions:

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

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

# Test local connectivity
curl -v http://localhost:9877/api/health

# Check network configuration
ss -tulpn | grep 9877

Solutions:

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

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

Solutions:

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

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

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

# Check Prometheus service
sudo systemctl status prometheus

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

Solutions:

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

# Check FFmpeg installation
ffmpeg -version

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

Solutions:

# 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

# 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

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

   sudo systemctl stop torrent-gateway nginx redis-server
   

2. Check system resources:

   df -h
   free -h
   top
   

3. Restore from backup:

   sudo /opt/torrent-gateway/scripts/restore.sh LATEST_BACKUP
   

4. Restart services:

   sudo systemctl start redis-server nginx torrent-gateway
   

Data Recovery

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

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

sudo /opt/torrent-gateway/scripts/health_check.sh | tee health_status.txt

System Information

# 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

# 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