Troubleshooting¶

Having issues with Torrentarr? This section provides solutions to common problems and debugging techniques.

Quick Links¶

• Common Issues - Frequently encountered problems and solutions
• Docker Issues - Docker-specific troubleshooting
• Database Issues - Database troubleshooting, corruption prevention, and recovery
• FAQ - Frequently asked questions

Common Problems¶

Connection Issues¶

Can't connect to qBittorrent or Arr instances?

Quick Fixes: - Verify all services are running - Check host/port configuration - Verify API keys are correct - Test connections from Torrentarr container/host

Detailed Guide: Connection Problems

Import Issues¶

Downloads complete but don't import to Arr?

Quick Fixes: - Check path mappings - Verify file permissions - Enable instant import - Check Arr logs

Detailed Guide: Import Failures

Docker Networking¶

Problems with Docker container communication?

Quick Fixes: - Use container names instead of localhost - Check Docker network configuration - Verify port mappings - Test inter-container connectivity

Detailed Guide: Docker Networking

Stalled Torrents¶

Torrents stuck and not completing?

Quick Fixes: - Check torrent health monitoring is enabled - Verify tracker connectivity - Check available disk space - Review torrent client logs

Detailed Guide: Stalled Torrents

Debugging Steps¶

1. Check Logs¶

Torrentarr logs provide detailed information about operations:

# View logs
docker logs torrentarr

# Follow logs in real-time
docker logs -f torrentarr

# Save logs to file
docker logs torrentarr > torrentarr.log 2>&1

# View logs
journalctl -u torrentarr

# Follow logs
journalctl -u torrentarr -f

# Recent logs
journalctl -u torrentarr -n 100

# Logs are in ~/config/logs/
tail -f ~/config/logs/Main.log

2. Verify Configuration¶

Check your configuration file for errors:

# Native
cat ~/config/config.toml

# Docker
docker exec torrentarr cat /config/config.toml

Common configuration mistakes: - Wrong API keys - Incorrect host/port - Missing required fields - Typos in service names

3. Test Connectivity¶

Verify services are accessible:

# Test qBittorrent
curl http://localhost:8080

# Test Radarr
curl http://localhost:7878/api/v3/system/status \
  -H "X-Api-Key: your-api-key"

# Test Sonarr
curl http://localhost:8989/api/v3/system/status \
  -H "X-Api-Key: your-api-key"

4. Check Service Status¶

Ensure all required services are running:

docker ps | grep -E "qbittorrent|radarr|sonarr|torrentarr"

systemctl status qbittorrent radarr sonarr torrentarr

5. Review Permissions¶

File permission issues can cause imports to fail:

# Check ownership
ls -la /path/to/downloads

# Check Torrentarr can read files
docker exec torrentarr ls -la /downloads

Getting Help¶

Before Asking for Help¶

1. Check the documentation:
2. Common Issues
3. Docker Troubleshooting

4. FAQ

5. Gather information:

6. Torrentarr version
7. Installation method (Docker/dotnet/binary)
8. Arr versions
9. Relevant log excerpts

10. Configuration (redact API keys!)

11. Search existing issues:

12. GitHub Issues
13. Discussions

Where to Get Help¶

• GitHub Issues - For bugs and feature requests
• GitHub Discussions - For questions and community support
• Discord - Real-time help from the community

Creating a Good Issue Report¶

Include:

1. Environment:

   Torrentarr version: 5.5.5
   Installation: Docker
   OS: Ubuntu 22.04
   qBittorrent: 4.6.0
   Radarr: 5.0.0
   

2. Problem Description:

3. What you expected to happen
4. What actually happened

5. Steps to reproduce

6. Relevant Logs:

   [Include relevant log excerpts]
   

7. Configuration: toml # Redact sensitive information! [qBit] Host = "http://qbittorrent" Port = 8080 UserName = "admin" Password = "REDACTED"

Debug Mode¶

Enable debug logging for more detailed information:

[Settings]
LogLevel = "DEBUG"

Warning: Debug logs can be very verbose and may impact performance. Only enable when troubleshooting.

Performance Issues¶

High CPU Usage¶

Symptoms: Torrentarr consuming excessive CPU

Common Causes:

1. Too frequent torrent checks: toml [Settings] CheckInterval = 300 # Increase interval (default: 60)

2. Too many concurrent health checks: toml [Settings] MaxConcurrentChecks = 5 # Reduce concurrent operations

3. Large torrent counts:

4. Limit categories to only what Torrentarr needs to manage

5. Use category filtering in qBittorrent

6. FFprobe validation on large files: toml [Settings] FFprobeAutoUpdate = false # Temporarily disable to test

Monitor Resource Usage:

# Docker
docker stats torrentarr --no-stream

# Native
ps aux | grep torrentarr
top -p $(pidof torrentarr)

High Memory Usage¶

Symptoms: Torrentarr using excessive RAM

Solutions:

1. Reduce log retention: toml [Settings] LogRetentionDays = 7 # Reduce from default 30

2. Limit torrent history: toml [Settings] TorrentHistoryDays = 30 # Clean old entries

3. Vacuum database regularly:

   sqlite3 ~/config/torrentarr.db "VACUUM;"
   

4. Restart Torrentarr periodically:

5. Set up a cron job or systemd timer for weekly restarts

Slow WebUI Response¶

Symptoms: WebUI is slow or unresponsive

Solutions:

1. Reduce data fetching:
2. Limit log entries displayed (50-100 instead of 500)
3. Use filters to reduce table sizes

4. Disable auto-refresh when not actively monitoring

5. Check API response times:

   time curl http://localhost:6969/api/health
   

6. Database optimization:

   # Check database size
   ls -lh ~/config/torrentarr.db
   
   # If > 100MB, vacuum
   sqlite3 ~/config/torrentarr.db "VACUUM;"
   

7. Browser performance:

8. Clear browser cache
9. Disable unnecessary browser extensions
10. Try a different browser

Slow Import Processing¶

Symptoms: Torrents complete but imports take a long time

Solutions:

1. Enable instant imports: toml [Radarr-Movies] InstantImport = true # Trigger immediate imports

2. Optimize Arr refresh intervals: toml [Radarr-Movies] RefreshDownloadsTimer = 1 # Check every 1 minute

3. Check Arr instance performance:

4. Review Arr logs for slow operations
5. Optimize Arr database

6. Reduce Arr's own refresh intervals

7. Path mapping issues:

8. Verify paths are consistent across all services
9. See Path Mapping Guide

Network Issues¶

Timeout Errors¶

Symptoms: "Connection timeout" errors in logs

Solutions:

1. Increase timeout values: toml [Settings] ConnectionTimeout = 60 # Increase from default 30 ReadTimeout = 120 # Increase from default 60

2. Check network connectivity:

   # Test from Torrentarr container/host
   ping qbittorrent
   ping radarr
   curl -v http://qbittorrent:8080
   

3. Verify services are responding:

   # Check service health
   docker exec torrentarr curl http://qbittorrent:8080/api/v2/app/version
   

4. Review firewall rules:

   # Ubuntu/Debian
   sudo ufw status
   
   # Check if ports are open
   sudo netstat -tulpn | grep 8080
   

DNS Resolution Issues¶

Symptoms: "Name or service not known" errors

Solutions:

1. Use IP addresses instead of hostnames: toml [qBit] Host = "http://192.168.1.100" # Instead of hostname

2. Check DNS configuration (Docker):

   services:
     torrentarr:
       dns:
         - 8.8.8.8
         - 1.1.1.1
   

3. Verify container can resolve names:

   docker exec torrentarr nslookup radarr
   docker exec torrentarr ping -c 3 radarr
   

4. Use Docker network aliases:

   services:
     radarr:
       networks:
         mediastack:
           aliases:
             - radarr
   

Connection Refused¶

Symptoms: "Connection refused" when trying to reach services

Solutions:

1. Verify service is listening:

   docker ps | grep radarr  # Check if running
   netstat -tulpn | grep 7878  # Check if listening
   

2. Check bind address:

3. Services should bind to 0.0.0.0 not 127.0.0.1 for Docker

4. Verify port mappings (Docker):

   docker port torrentarr
   docker port radarr
   

5. Test from correct network namespace:

   # From within Torrentarr container
   docker exec torrentarr curl http://radarr:7878
   

Configuration Issues¶

Invalid TOML Syntax¶

Symptoms: Torrentarr won't start, "Invalid configuration" error

Common Mistakes:

1. Missing quotes:

   # ❌ Wrong
   Host = http://localhost
   
   # ✅ Correct
   Host = "http://localhost"
   

2. Wrong quotes:

   # ❌ Wrong (single quotes don't work for all values)
   APIKey = 'abc123'
   
   # ✅ Correct
   APIKey = "abc123"
   

3. Unclosed brackets:

   # ❌ Wrong
   [[Radarr]
   Name = "Movies"
   
   # ✅ Correct
   [[Radarr]]
   Name = "Movies"
   

4. Duplicate sections:

   # ❌ Wrong (duplicate [Settings])
   [Settings]
   LogLevel = "INFO"
   
   [Settings]
   CheckInterval = 60
   
   # ✅ Correct
   [Settings]
   LogLevel = "INFO"
   CheckInterval = 60
   

Validate TOML:

# .NET / runtime validation
python3 -c "import toml; toml.load(open('config.toml'))"

# Online validator
# Copy config to https://www.toml-lint.com/

Missing Required Fields¶

Symptoms: "Config key 'X' requires a value" error

Solutions:

Check these required fields are set:

[qBit]
Host = "localhost"  # REQUIRED
Port = 8080
# UserName and Password (if qBit has auth enabled)

[Radarr-Movies]
URI = "http://localhost:7878"   # REQUIRED
APIKey = "your-api-key"         # REQUIRED
Category = "radarr"             # REQUIRED (must match qBit download client)

Environment Variable Overrides Not Working¶

Symptoms: Config path environment variable not applied

Solutions:

1. Use the correct variable: Torrentarr only reads TORRENTARR_CONFIG (path to config.toml). It does not support per-setting env overrides.

   export TORRENTARR_CONFIG=/path/to/config/config.toml
   

2. Verify variable is passed to container:

   docker exec torrentarr env | grep TORRENTARR_CONFIG
   

3. In Docker Compose:

   environment:
     TORRENTARR_CONFIG: /config/config.toml
   

Automated Search Issues¶

Searches Not Triggering¶

Symptoms: Torrentarr doesn't search for missing content

Solutions:

1. Enable search functionality: toml [Radarr-Movies] [Radarr.Search] SearchMissing = true

2. Check search intervals: toml SearchRequestsEvery = 300 # Search every 5 minutes

3. Verify Arr has indexers:

4. Radarr/Sonarr/Lidarr must have working indexers configured

5. Test indexers in Arr UI

6. Review search logs:

   grep -i "search" ~/config/logs/Radarr-Movies.log
   

7. Check for rate limiting:

8. Some indexers rate limit searches
9. Review indexer API limits

Too Many Searches¶

Symptoms: Overwhelming indexers with searches, rate limited

Solutions:

1. Increase search interval: toml SearchRequestsEvery = 600 # 10 minutes instead of 5

2. Reduce search limit: toml SearchLimit = 3 # Fewer concurrent searches

3. Disable upgrade searches temporarily: toml DoUpgradeSearch = false QualityUnmetSearch = false

4. Monitor indexer stats:

5. Check Prowlarr for indexer statistics
6. Review API hit counts

Seeding & Tracker Issues¶

Torrents Removed Too Early¶

Symptoms: Torrents deleted before reaching seeding goals

Solutions:

1. Adjust seeding limits: toml [Radarr-Movies] [Radarr.Torrent.SeedingMode] MaxUploadRatio = 2.0 # Increase ratio MaxSeedingTime = 1209600 # 14 days in seconds RemoveTorrent = 4 # Remove only when BOTH met

2. Check tracker-specific rules: toml [[Radarr.Torrent.Trackers]] Name = "PrivateTracker" URI = "https://tracker.example.com" MaxUploadRatio = 3.0 # Higher for private trackers

3. Disable automatic removal: toml RemoveTorrent = -1 # Never auto-remove

Dead Tracker Detection Issues¶

Symptoms: Torrents marked as failed due to temporary tracker issues

Solutions:

1. Increase stall delay: toml StalledDelay = 30 # 30 minutes before considering stalled

2. Disable tracker error removal: toml RemoveDeadTrackers = false

3. Customize tracker error messages: toml RemoveTrackerWithMessage = [ # Only remove on these specific errors "info hash is not authorized with this tracker" ]

Logging Issues¶

Too Many Logs¶

Symptoms: Log files growing too large

Solutions:

1. Reduce log level: toml [Settings] LogLevel = "INFO" # Change from DEBUG

2. Enable log rotation: toml LogRotation = true LogMaxSize = 10485760 # 10 MB LogBackupCount = 5

3. Reduce retention: toml LogRetentionDays = 7 # Keep only 1 week

Can't Find Logs¶

Symptoms: Don't know where logs are located

Log Locations:

# Console logs
docker logs torrentarr

# File logs (if volume mounted)
ls -la /path/to/config/logs/

~/config/logs/
├── Main.log
├── WebUI.log
└── Radarr-Movies.log

# Journald logs
journalctl -u torrentarr -f

# File logs
ls -la /home/torrentarr/config/logs/

Update & Upgrade Issues¶

Update Fails¶

Symptoms: Auto-update or manual update fails

Solutions:

1. Check for sufficient disk space:

   df -h /path/to/torrentarr
   

2. Verify permissions: the Host process must be able to write next to (or replace) its executable and use temp space for the download.

3. Check for breaking changes:

4. Review CHANGELOG.md

5. Backup config before upgrading

6. Manual update:

   # Docker
   docker-compose pull torrentarr
   docker-compose up -d torrentarr
   
   # Binary: download the matching asset from GitHub Releases, replace the executable, restart
   

Version Mismatch Issues¶

Symptoms: Errors after update, incompatible features

Solutions:

1. Check version:

   torrentarr --version  # native
   docker exec torrentarr torrentarr --version  # Docker
   

2. Review config migrations:

3. Torrentarr auto-migrates config on version change

4. Check logs for migration messages

5. Rollback if needed:

   # Docker — pin image tag
   docker pull feramance/torrentarr:5.4.0
   
   # Binary — download the older release asset from GitHub and replace the executable
   

Clean Restart¶

Sometimes a clean restart resolves issues:

docker stop torrentarr
docker rm torrentarr
# Then recreate with your docker run command

sudo systemctl restart torrentarr

# Stop Torrentarr (Ctrl+C if running in foreground)
# Then restart
torrentarr

Database Issues¶

If the database becomes corrupt:

1. Backup existing database:

   cp ~/config/torrentarr.db ~/config/torrentarr.db.backup
   

2. Let Torrentarr recreate:

   rm ~/config/torrentarr.db
   # Restart Torrentarr - it will create a new database
   

3. Recovery: Torrentarr has automatic database recovery. Check logs for recovery messages.

Still Need Help?¶

If you've tried the troubleshooting steps and still have issues:

1. Review Common Issues for detailed solutions
2. Check Docker-specific issues if using Docker
3. Search GitHub Issues
4. Ask in GitHub Discussions

We're here to help! 🚀