Troubleshooting

Installation Issues

Docker container won’t start

Check logs:

docker logs decypharr

Common causes:

• Port 8282 already in use
• Invalid volume paths
• Permission issues on mounted directories

Fix:

docker-compose.yml

services:
  decypharr:
    ports:
      - "8283:8282"  # Use different external port
    volumes:
      - ./config:/config
    user: "1000:1000"  # Match your user ID

Binary: “permission denied”

Make executable:

chmod +x decypharr
./decypharr

Authentication Issues

API token not working

1. Regenerate token:

   curl -X POST -H "Authorization: Bearer OLD_TOKEN" \
     http://localhost:8282/api/refresh-token

2. Check token in /config/config.json (api_token field)
3. Ensure Authorization header format: Bearer YOUR_TOKEN

Mount Issues

Mount point empty

Check mount status:

ls -la /mnt/decypharr
mount | grep decypharr

Common causes:

• FUSE not available
• Permission issues
• Mount path doesn’t exist

Fix (Docker):

services:
  decypharr:
    devices:
      - /dev/fuse
    cap_add:
      - SYS_ADMIN
    security_opt:
      - apparmor:unconfined

Fix (Binary):

# Install FUSE
sudo apt install fuse  # Debian/Ubuntu
sudo yum install fuse  # CentOS/RedHat

# Add user to fuse group
sudo usermod -a -G fuse $USER

“Transport endpoint is not connected”

Mount crashed. Unmount and restart:

# Force unmount
sudo fusermount -u /mnt/decypharr
# or
sudo umount -l /mnt/decypharr

# Restart Decypharr
docker restart decypharr

“Permission denied” accessing files

Set correct UID/GID:

{
  "mount": {
    "dfs": {
      "uid": 1001,
      "gid": 1001,
      "allow_other": true
    }
  }
}

Find your user ID:

id your_username

Debrid Provider Issues

”API key invalid”

1. Verify key at provider dashboard
2. Check for typos/extra spaces
3. Regenerate API key
4. Update config and restart

”No free slots”

Check slots:

• Real Debrid: https://real-debrid.com/torrents
• All Debrid: Dashboard

Solutions:

1. Remove old torrents manually
2. Configure slot management:

   {
     "debrids": [
       {
         "minimum_free_slot": 10,
         "limit": 100
       }
     ]
   }

3. Add backup provider

Rate limit errors

Reduce request rate:

{
  "debrids": [
    {
      "rate_limit": "100/minute",
      "workers": 25
    }
  ]
}

Or add more API keys:

{
  "download_api_keys": ["KEY1", "KEY2", "KEY3"]
}

“Link unavailable” or “Download failed”

Links expire after auto_expire_links_after (default 24h). Repair worker should fix automatically.

Manual fix:

1. Go to Repair page
2. Click “Scan Now”
3. Process detected jobs

Usenet Issues

Connection failed to NNTP server

Check connectivity:

telnet news.provider.com 563

Verify config:

• Correct host/port
• Valid username/password
• SSL enabled if provider requires
• Provider account active

NZB processing timeout

Increase timeout:

{
  "usenet": {
    "processing_timeout": "20m",
    "availability_sample_percent": 5
  }
}

Incomplete downloads

1. Enable repair:

   {"usenet": {"skip_repair": false}}

2. Check provider retention (old content may be incomplete)
3. Try different provider

”Too many connections”

Provider limit exceeded. Reduce:

{
  "usenet": {
    "max_connections": 10
  }
}

And per-provider:

{
  "usenet": {
    "providers": [
      {"max_connections": 15}
    ]
  }
}

Arr Integration Issues

Test connection fails

1. Check accessibility:

   curl http://decypharr:8282/version

2. Verify credentials in Arr match config
3. Check firewall rules
4. Try IP instead of hostname

Downloads stuck “Queued” in Arr

1. Check Decypharr logs for errors
2. Verify Debrid provider has free slots
3. Check download_uncached setting in Arr config
4. Manually test adding torrent via Decypharr UI

Files not importing

Path mapping issue:

Arr and Decypharr must see files at identical paths:

# Both services
volumes:
  - /mnt/media:/mnt/media

Check download action:

{
  "arrs": [
    {
      "name": "Sonarr",
      "download_action": "symlink"  # For mounts
    }
  ]
}

Torrent shows completed but Arr shows downloading

Arr sync delay. Wait 1-2 minutes or trigger manual import in Arr.

Performance Issues

High CPU usage

Check:

docker stats decypharr

Causes:

• Too many concurrent workers
• Repair loop
• Usenet processing

Solutions:

1. Reduce workers:

   {
     "debrids": [{"workers": 25}],
     "repair": {"workers": 1, "enabled": false}
   }

2. Temporarily disable repair
3. Check logs for errors/loops

High memory usage

Usenet streams use disk buffer. Check:

{
  "usenet": {
    "disk_buffer_path": "/cache/usenet"
  }
}

Ensure sufficient disk space.

For Rclone:

{
  "mount": {
    "rclone": {
      "vfs_cache_max_size": "5GB"
    }
  }
}

Slow streaming/buffering

DFS:

{
  "mount": {
    "dfs": {
      "chunk_size": "20MB",
      "disk_cache_size": "100GB"
    }
  }
}

Usenet:

{
  "usenet": {
    "read_ahead": "32MB",
    "max_connections": 20
  }
}

Check provider performance:

• Test speed from Debrid website
• Try different Usenet provider
• Check network bandwidth

Database growing large

Config stored in config.json (text). No separate database.

If logs are large:

{"log_level": "warn"}

WebDAV Issues

Can’t connect to WebDAV

1. Test URL:

   curl http://localhost:8282/webdav/

2. Check auth:

   {
     "use_auth": true,
     "enable_webdav_auth": true
   }

3. Verify credentials match config

Authentication keeps prompting

Clear browser cache or saved credentials.

For apps, provide full URL with auth:

http://username:password@decypharr:8282/webdav/

Files won’t play in WebDAV client

WebDAV has no local cache - streaming depends on Debrid/Usenet speed. For better performance, use DFS mount instead of WebDAV.

Repair Worker Issues

Repair jobs stuck “Processing”

1. Check workers:

   {"repair": {"workers": 2}}

2. Check rate limits (might be throttled)
3. Restart Decypharr:

   docker restart decypharr

False positives in repair

Increase scan interval:

{
  "repair": {
    "interval": "2h",
    "auto_process": false
  }
}

Review jobs manually before processing.

Repair not detecting issues

1. Verify repair enabled:

   {"repair": {"enabled": true}}

2. Check per-Arr skip:

   {
     "arrs": [
       {"skip_repair": false}
     ]
   }

3. Manual trigger:

   curl -X POST -H "Authorization: Bearer TOKEN" \
     http://localhost:8282/api/repair

Debugging

Enable debug logging

{"log_level": "debug"}

Docker:

docker logs -f decypharr

Binary:

./decypharr 2>&1 | tee decypharr.log

Check configuration

View current config:

curl -H "Authorization: Bearer TOKEN" \
  http://localhost:8282/api/config | jq

Validate JSON:

cat /config/config.json | jq

Health check

# Version
curl http://localhost:8282/version

# Torrents (requires auth)
curl -H "Authorization: Bearer TOKEN" \
  http://localhost:8282/api/torrents

Reset to defaults

Backup current config:

cp /config/config.json /config/config.json.backup

Delete config:

rm /config/config.json

Restart - setup wizard will run

Getting Help

If you can’t resolve the issue:

1. Check GitHub Issues: https://github.com/sirrobot01/decypharr/issues
2. Provide:
   • Decypharr version (/version)
   • Relevant logs (with log_level: debug)
   • Config (sensitive values redacted)
   • Steps to reproduce
3. Include system info:
   • OS/Docker version
   • Mount type
   • Providers used

Sanitize config before sharing:

cat config.json | sed 's/"api_key": ".*"/"api_key": "REDACTED"/g'