arr-suite-template-bootstrap/docs/TROUBLESHOOTING.md

Troubleshooting Guide

This guide covers common issues you might encounter when deploying and running the Arrs media stack, along with step-by-step solutions.

Table of Contents

1. Quick Diagnostics
2. Deployment Issues
3. Service Issues
4. Network and Connectivity
5. Storage and Permissions
6. VPN Issues
7. Performance Issues
8. Backup and Recovery
9. Getting Help

Quick Diagnostics

Essential Commands

# Check all container status
docker ps -a

# Check system resources
htop
df -h

# Check logs for all services
docker-compose logs --tail=50

# Check specific service logs
docker logs [service_name] --tail=50

# Test network connectivity
ping google.com
curl -I https://google.com

Health Check Script

Create a quick health check script:

#!/bin/bash
# Save as ~/check_health.sh

echo "=== System Resources ==="
df -h | grep -E "(Filesystem|/dev/)"
free -h
echo ""

echo "=== Docker Status ==="
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
echo ""

echo "=== Service Health ==="
services=("sonarr" "radarr" "lidarr" "bazarr" "prowlarr" "qbittorrent" "plex" "tubearchivist" "tubearchivist-es" "tubearchivist-redis" "jellyseerr" "tautulli")
for service in "${services[@]}"; do
    if docker ps | grep -q $service; then
        echo "✅ $service: Running"
    else
        echo "❌ $service: Not running"
    fi
done

Make it executable and run:

chmod +x ~/check_health.sh
~/check_health.sh

Deployment Issues

Ansible Playbook Fails

Issue: "Permission denied" errors

Symptoms:

TASK [Create docker user] ****
fatal: [localhost]: FAILED! => {"msg": "Permission denied"}

Solutions:

1. Ensure you're running as a user with sudo privileges:

   sudo -v  # Test sudo access
   

2. If using a non-root user, ensure they're in the sudo group:

   sudo usermod -aG sudo $USER
   # Log out and back in
   

3. Run with explicit sudo if needed:

   ansible-playbook -i inventory/hosts site.yml --become --ask-become-pass
   

Issue: "Docker not found" after installation

Symptoms:

TASK [Start Docker service] ****
fatal: [localhost]: FAILED! => {"msg": "Could not find the requested service docker"}

Solutions:

1. Manually install Docker:

   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh
   sudo usermod -aG docker $USER
   # Log out and back in
   

2. Restart the deployment:

   ansible-playbook -i inventory/hosts site.yml
   

Issue: "Port already in use"

Symptoms:

ERROR: for sonarr  Cannot start service sonarr: driver failed programming external connectivity on endpoint sonarr: Bind for 0.0.0.0:8989 failed: port is already allocated

Solutions:

1. Check what's using the port:

   sudo netstat -tulpn | grep :8989
   sudo lsof -i :8989
   

2. Stop the conflicting service or change ports in group_vars/all.yml:

   ports:
     sonarr: 8990  # Changed from 8989
   

3. Redeploy:

   ansible-playbook -i inventory/hosts site.yml
   

Configuration File Issues

Issue: YAML syntax errors

Symptoms:

ERROR! Syntax Error while loading YAML.

Solutions:

1. Validate YAML syntax:

   python3 -c "import yaml; yaml.safe_load(open('group_vars/all.yml'))"
   

2. Common YAML mistakes:

   • Missing quotes around special characters
   • Incorrect indentation (use spaces, not tabs)
   • Missing colons after keys

3. Use a YAML validator online or in your editor

Issue: Undefined variables

Symptoms:

AnsibleUndefinedVariable: 'vpn_provider' is undefined

Solutions:

1. Check if variable is defined in group_vars/all.yml
2. Ensure proper indentation and spelling
3. Add missing variables:

   vpn_provider: "nordvpn"  # Add if missing
   

Service Issues

Services Won't Start

Issue: Container exits immediately

Check logs:

docker logs [container_name]

Common causes and solutions:

1. Permission issues:

   # Fix ownership
   sudo chown -R 1000:1000 /home/arrs/docker
   sudo chown -R 1000:1000 /home/arrs/media
   

2. Missing directories:

   # Create missing directories
   mkdir -p /home/arrs/media/{movies,tv,music,downloads}
   mkdir -p /home/arrs/docker/{sonarr,radarr,lidarr,bazarr,prowlarr,qbittorrent}
   

3. Configuration file corruption:

   # Remove corrupted config and restart
   sudo rm -rf /home/arrs/docker/sonarr/config.xml
   docker restart sonarr
   

Issue: Service starts but web interface not accessible

Symptoms:

• Container shows as running
• Can't access web interface

Solutions:

1. Check if service is listening on correct port:

   docker exec sonarr netstat -tulpn | grep :8989
   

2. Check firewall:

   sudo ufw status
   sudo ufw allow 8989  # Open required port
   

3. Check if service is bound to localhost only:

   docker logs sonarr | grep -i "listening\|bind"
   

Database Issues

Issue: Sonarr/Radarr database corruption

Symptoms:

• Service won't start
• Logs show database errors
• Web interface shows errors

Solutions:

1. Backup current database:

   cp /home/arrs/docker/sonarr/sonarr.db /home/arrs/docker/sonarr/sonarr.db.backup
   

2. Try database repair:

   # Install sqlite3
   sudo apt install sqlite3
   
   # Check database integrity
   sqlite3 /home/arrs/docker/sonarr/sonarr.db "PRAGMA integrity_check;"
   
   # Repair if needed
   sqlite3 /home/arrs/docker/sonarr/sonarr.db ".recover" | sqlite3 /home/arrs/docker/sonarr/sonarr_recovered.db
   

3. Restore from backup:

   # Stop service
   docker stop sonarr
   
   # Restore backup
   cp /home/arrs/docker/sonarr/sonarr.db.backup /home/arrs/docker/sonarr/sonarr.db
   
   # Start service
   docker start sonarr
   

Network and Connectivity

Can't Access Services from Outside

Issue: Services only accessible from localhost

Solutions:

1. Check Docker network configuration:

   docker network ls
   docker network inspect arrs_network
   

2. Verify port bindings:

   docker port sonarr
   

3. Check VPS firewall:

   # Ubuntu/Debian
   sudo ufw status
   sudo ufw allow 8989
   
   # CentOS/RHEL
   sudo firewall-cmd --list-ports
   sudo firewall-cmd --add-port=8989/tcp --permanent
   sudo firewall-cmd --reload
   

4. Check cloud provider firewall:

   • AWS: Security Groups
   • DigitalOcean: Cloud Firewalls
   • Google Cloud: VPC Firewall Rules

DNS Resolution Issues

Issue: Services can't resolve external domains

Symptoms:

• Can't download metadata
• Indexer tests fail
• Updates don't work

Solutions:

1. Check DNS in containers:

   docker exec sonarr nslookup google.com
   docker exec sonarr cat /etc/resolv.conf
   

2. Fix DNS configuration:

   # Edit Docker daemon configuration
   sudo nano /etc/docker/daemon.json
   

   Add:

   {
     "dns": ["8.8.8.8", "1.1.1.1"]
   }
   

   Restart Docker:

   sudo systemctl restart docker
   docker-compose up -d
   

Storage and Permissions

Permission Denied Errors

Issue: Services can't write to media directories

Symptoms:

• Downloads fail
• Can't move files
• Import errors

Solutions:

1. Check current permissions:

   ls -la /home/arrs/media/
   ls -la /home/arrs/docker/
   

2. Fix ownership:

   # Get user/group IDs
   id arrs
   
   # Fix ownership (replace 1000:1000 with actual IDs)
   sudo chown -R 1000:1000 /home/arrs/media
   sudo chown -R 1000:1000 /home/arrs/docker
   

3. Fix permissions:

   sudo chmod -R 755 /home/arrs/media
   sudo chmod -R 755 /home/arrs/docker
   

4. Verify container user mapping:

   docker exec sonarr id
   

Disk Space Issues

Issue: No space left on device

Solutions:

1. Check disk usage:

   df -h
   du -sh /home/arrs/* | sort -hr
   

2. Clean up Docker:

   # Remove unused containers, networks, images
   docker system prune -a
   
   # Remove unused volumes (CAREFUL!)
   docker volume prune
   

3. Clean up logs:

   # Truncate large log files
   sudo truncate -s 0 /var/log/syslog
   sudo truncate -s 0 /var/log/kern.log
   
   # Clean Docker logs
   docker logs sonarr 2>/dev/null | wc -l  # Check log size
   sudo sh -c 'echo "" > $(docker inspect --format="{{.LogPath}}" sonarr)'
   

4. Move media to external storage:

   # Mount additional storage
   sudo mkdir /mnt/media
   sudo mount /dev/sdb1 /mnt/media
   
   # Update configuration
   nano group_vars/all.yml
   # Change media_root: "/mnt/media"
   

TubeArchivist Issues

TubeArchivist Won't Start

Issue: Elasticsearch container fails to start

Symptoms:

• TubeArchivist shows "Elasticsearch connection failed"
• Elasticsearch container exits with memory errors
• Web interface shows database connection errors

Solutions:

1. Increase memory allocation:

   # Check available memory
   free -h
   
   # If less than 4GB available, reduce ES memory in docker-compose.yml
   # Change ES_JAVA_OPTS from -Xms1g -Xmx1g to -Xms512m -Xmx512m
   

2. Fix Elasticsearch permissions:

   sudo chown -R 1000:1000 /home/arrs/docker/tubearchivist/es
   sudo chmod -R 755 /home/arrs/docker/tubearchivist/es
   

3. Check disk space:

   df -h /home/arrs/docker/tubearchivist/
   

Issue: Downloads fail or get stuck

Symptoms:

• Videos remain in "Pending" status
• Download queue shows errors
• yt-dlp errors in logs

Solutions:

1. Update yt-dlp:

   docker exec tubearchivist pip install --upgrade yt-dlp
   docker restart tubearchivist
   

2. Check YouTube channel/video availability:

   • Verify the channel/video is still available
   • Check if the channel has geographic restrictions
   • Try downloading a different video to test

3. Clear download queue:

   # Access TubeArchivist web interface
   # Go to Downloads → Queue → Clear Failed
   

4. Check storage space:

   df -h /home/arrs/media/youtube
   

Issue: Videos won't play or thumbnails missing

Symptoms:

• Videos show but won't play
• Missing thumbnails
• Playback errors

Solutions:

1. Check file permissions:

   ls -la /home/arrs/media/youtube/
   sudo chown -R 1000:1000 /home/arrs/media/youtube
   

2. Regenerate thumbnails:

   • Go to Settings → Application → Reindex
   • Select "Thumbnails" and run reindex

3. Check video file integrity:

   # Test video files
   find /home/arrs/media/youtube -name "*.mp4" -exec file {} \;
   

TubeArchivist Performance Issues

Issue: Slow downloads or high CPU usage

Solutions:

1. Limit concurrent downloads:

   • Go to Settings → Download → Max concurrent downloads
   • Reduce from default (4) to 1-2 for lower-end systems

2. Adjust video quality:

   • Go to Settings → Download → Video quality
   • Choose lower quality (720p instead of 1080p) to reduce processing

3. Schedule downloads during off-peak hours:

   • Go to Settings → Scheduling
   • Set download windows for low-usage periods

Issue: Database performance problems

Solutions:

1. Optimize Elasticsearch:

   # Increase refresh interval
   docker exec tubearchivist-es curl -X PUT "localhost:9200/_settings" -H 'Content-Type: application/json' -d'
   {
     "index": {
       "refresh_interval": "30s"
     }
   }'
   

2. Clean up old data:

   • Go to Settings → Application → Cleanup
   • Remove old downloads and unused thumbnails

VPN Issues

VPN Won't Connect

Issue: Gluetun fails to connect

Check logs:

docker logs gluetun --tail=50

Common solutions:

1. Wrong credentials:

   # Verify in group_vars/all.yml
   openvpn_user: "correct_username"
   openvpn_password: "correct_password"
   

2. Unsupported server location:

   # Try different countries
   vpn_countries: "Netherlands,Germany"
   

3. Provider API issues:

   # Try manual server selection
   vpn_server_hostnames: "nl123.nordvpn.com"
   

Issue: qBittorrent can't connect through VPN

Solutions:

1. Check network mode:

   docker inspect qbittorrent | grep NetworkMode
   # Should show: "NetworkMode": "service:gluetun"
   

2. Test connectivity:

   # Test from qBittorrent container
   docker exec qbittorrent curl -s https://ipinfo.io/ip
   

3. Restart VPN stack:

   docker restart gluetun
   docker restart qbittorrent
   

Performance Issues

Slow Performance

Issue: Services are slow or unresponsive

Solutions:

1. Check system resources:

   htop
   iotop  # Install with: sudo apt install iotop
   

2. Optimize Docker:

   # Limit container resources in docker-compose.yml
   services:
     sonarr:
       deploy:
         resources:
           limits:
             memory: 512M
           reservations:
             memory: 256M
   

3. Optimize database:

   # Vacuum SQLite databases
   sqlite3 /home/arrs/docker/sonarr/sonarr.db "VACUUM;"
   sqlite3 /home/arrs/docker/radarr/radarr.db "VACUUM;"
   

4. Check disk I/O:

   # Test disk speed
   dd if=/dev/zero of=/tmp/test bs=1M count=1000
   rm /tmp/test
   

High CPU Usage

Issue: Containers using too much CPU

Solutions:

1. Identify problematic containers:

   docker stats
   

2. Check for runaway processes:

   docker exec sonarr ps aux
   

3. Limit CPU usage:

   # In docker-compose.yml
   services:
     sonarr:
       deploy:
         resources:
           limits:
             cpus: '0.5'  # Limit to 50% of one CPU core
   

Backup and Recovery

Backup Issues

Issue: Backup script fails

Check backup logs:

# Check if backup script exists
ls -la /home/arrs/scripts/backup.sh

# Check backup logs
tail -f /var/log/arrs-backup.log

Solutions:

1. Fix permissions:

   chmod +x /home/arrs/scripts/backup.sh
   

2. Test backup manually:

   sudo /home/arrs/scripts/backup.sh
   

3. Check backup destination:

   df -h /home/arrs/backups
   

Recovery Procedures

Issue: Need to restore from backup

Steps:

1. Stop all services:

   docker-compose down
   

2. Restore configuration:

   # Extract backup
   tar -xzf /home/arrs/backups/arrs-backup-YYYYMMDD.tar.gz -C /home/arrs/
   

3. Fix permissions:

   sudo chown -R 1000:1000 /home/arrs/docker
   

4. Start services:

   docker-compose up -d
   

Getting Help

Before Asking for Help

1. Check logs:

   docker logs [service_name] --tail=100
   

2. Gather system information:

   # Create debug info
   echo "=== System Info ===" > debug.txt
   uname -a >> debug.txt
   docker --version >> debug.txt
   docker-compose --version >> debug.txt
   
   echo "=== Container Status ===" >> debug.txt
   docker ps -a >> debug.txt
   
   echo "=== Disk Usage ===" >> debug.txt
   df -h >> debug.txt
   
   echo "=== Memory Usage ===" >> debug.txt
   free -h >> debug.txt
   

3. Sanitize sensitive information:

   • Remove passwords, API keys, personal paths
   • Replace IP addresses with placeholders

Where to Get Help

1. GitHub Issues: Create an issue with:

   • Clear description of the problem
   • Steps to reproduce
   • Error messages
   • System information
   • Configuration (sanitized)

2. Community Forums:

   • r/selfhosted
   • r/sonarr, r/radarr
   • Discord servers for specific applications

3. Documentation:

   • Official documentation for each service
   • Docker documentation
   • Ansible documentation

Common Support Questions

Q: "It doesn't work" A: Please provide specific error messages and logs.

Q: "Can't access from outside" A: Check firewall settings and port configurations.

Q: "Downloads don't start" A: Check indexer configuration and download client settings.

Q: "VPN not working" A: Verify credentials and check Gluetun logs.

Q: "Running out of space" A: Clean up Docker images and logs, consider external storage.

Emergency Recovery

If everything breaks:

1. Stop all services:

   docker-compose down
   

2. Backup current state:

   sudo tar -czf emergency-backup-$(date +%Y%m%d).tar.gz /home/arrs/docker
   

3. Reset to clean state:

   # Remove all containers and volumes
   docker system prune -a --volumes
   
   # Redeploy
   ansible-playbook -i inventory/hosts site.yml
   

4. Restore data from backups if needed

Remember: Most issues are fixable with patience and systematic troubleshooting. Don't panic, and always backup before making major changes!