07_Troubleshooting_Guide - nzbgetcom/Extension-RemoveSamples GitHub Wiki

Troubleshooting Guide

Common issues and solutions for RemoveSamples-NZBGet extension problems.

🎯 Quick Diagnostic Steps

Before diving into specific issues, try these quick diagnostic steps:

1. Enable Debug Mode

Settings → Extension Manager → RemoveSamples → Debug: Yes

This provides detailed logging to help identify issues.

2. Check Extension Status

Settings → Extension Manager → Installed Extensions

Verify RemoveSamples appears and shows correct version.

3. Review Recent Logs

Settings → Logging → Messages

Look for RemoveSamples-related entries and error messages.

4. Test with Known Sample

Download content with obvious sample files to test detection.

🚨 Installation Issues

Extension Not Appearing in Extension Manager

Symptoms:

  • RemoveSamples not listed in Extension Manager
  • No configuration options available
  • Extension dropdown doesn't show RemoveSamples

Possible Causes:

  • Incorrect file permissions
  • Wrong directory structure
  • Missing manifest.json file
  • NZBGet needs restart

Solutions:

Check File Structure

# Verify correct structure
ls -la /path/to/nzbget/scripts/RemoveSamples/
# Should show:
# main.py (executable)
# manifest.json (readable)

Fix Permissions (Linux/Unix)

# Set correct permissions
chmod 755 /path/to/nzbget/scripts/RemoveSamples/main.py
chmod 644 /path/to/nzbget/scripts/RemoveSamples/manifest.json

# Fix ownership if needed
chown -R nzbget:nzbget /path/to/nzbget/scripts/RemoveSamples/

Verify Manifest File

# Check manifest.json is valid
python3 -m json.tool /path/to/nzbget/scripts/RemoveSamples/manifest.json

Force NZBGet Restart

# Complete restart (not just reload)
sudo systemctl stop nzbget
sleep 5
sudo systemctl start nzbget

Permission Denied Errors

Symptoms:

[ERROR] Permission denied: /path/to/scripts/RemoveSamples/main.py
[ERROR] Failed to execute extension script

Solutions:

For Linux/Unix Systems

# Make script executable
chmod +x /path/to/nzbget/scripts/RemoveSamples/main.py

# Check script owner
ls -la /path/to/nzbget/scripts/RemoveSamples/main.py
# Should be owned by nzbget user

# Fix ownership if wrong
sudo chown nzbget:nzbget /path/to/nzbget/scripts/RemoveSamples/main.py

For Docker Environments

# Check container user ID
docker exec nzbget id

# Fix permissions on host
sudo chown -R 1000:1000 /path/to/scripts/RemoveSamples/

# For Unraid specifically
sudo chown -R nobody:users /mnt/user/appdata/nzbget/scripts/RemoveSamples/

🐳 Docker & Unraid Specific Issues

Container Permission Issues

Symptoms:

[ERROR] Permission denied: /opt/nzbget/scripts/RemoveSamples/main.py
[ERROR] Cannot access scripts directory

Solutions:

Unraid Permission Fix

# Fix ownership for Unraid
chown -R nobody:users /mnt/user/appdata/nzbget/scripts/RemoveSamples/

# Set correct permissions
chmod 755 /mnt/user/appdata/nzbget/scripts/RemoveSamples/main.py
chmod 644 /mnt/user/appdata/nzbget/scripts/RemoveSamples/manifest.json

Docker Permission Fix

# Check container user
docker exec nzbget id

# For LSIO containers (abc user)
chown -R abc:abc /path/to/scripts/RemoveSamples/

# For standard containers
chown -R 1000:1000 /path/to/scripts/RemoveSamples/

Volume Mount Issues

# Verify volume mounts
docker inspect nzbget | grep -A 10 Mounts

# Ensure scripts directory is mounted
# Host: /path/to/scripts
# Container: /opt/nzbget/scripts

Path Mapping Problems

Symptoms:

  • Extension not appearing in NZBGet
  • Files not accessible by container
  • Permission errors during execution

Solutions:

Verify Unraid Paths

# Check NZBGet container settings
# Scripts path should be: /mnt/user/appdata/nzbget/scripts/
# Downloads path should be: /mnt/user/downloads/ or similar

# Verify files exist on host
ls -la /mnt/user/appdata/nzbget/scripts/RemoveSamples/

Check Docker Compose Volumes

# Ensure scripts volume is mounted
volumes:
  - /host/scripts:/opt/nzbget/scripts  # Must match NZBGet container paths
  - /host/downloads:/downloads

Container Environment Issues

Symptoms:

[ERROR] Python not found in container
[ERROR] Module import errors

Solutions:

Verify Python in Container

# Check Python availability
docker exec nzbget python3 --version

# If missing, use different base image or install Python

Common Docker Images Python Status

# LinuxServer NZBGet - Python included ✅
linuxserver/nzbget:latest

# Official NZBGet - May need Python installation ❓
nzbget/nzbget:latest

Install Python in Container (if needed)

# For Ubuntu/Debian based containers
docker exec nzbget apt update && apt install -y python3

# For Alpine based containers  
docker exec nzbget apk add python3

Unraid Specific Issues

Symptoms:

  • Extension works but configuration doesn't save
  • Frequent "extension not found" errors
  • Container restarts lose extension

Solutions:

Ensure Persistent Storage

# Verify appdata is persistent
# Extensions should be in: /mnt/user/appdata/nzbget/scripts/
# NOT in: /tmp/ or other temporary locations

Unraid Container Template Issues

# Check container template variables
# Scripts path mapping must be persistent
# User/Group must match (nobody:users)

Common Unraid NZBGet Settings

Container Variable: PUID=99
Container Variable: PGID=100
Volume Mapping: /mnt/user/appdata/nzbget/scripts/ → /opt/nzbget/scripts/
Volume Mapping: /mnt/user/downloads/ → /downloads/

Docker Network Issues

Symptoms:

  • RemoveSamples works but can't download extension updates
  • Network timeouts during installation

Solutions:

Check Container Network

# Verify container can access internet
docker exec nzbget ping -c 3 google.com

# Check DNS resolution
docker exec nzbget nslookup github.com

Manual Download Method

# If container can't download directly, download on host
cd /mnt/user/appdata/nzbget/scripts/RemoveSamples/
wget https://github.com/Anunnaki-Astronaut/RemoveSamples-NZBGet/raw/main/main.py
wget https://github.com/Anunnaki-Astronaut/RemoveSamples-NZBGet/raw/main/manifest.json
chown nobody:users *

Python Not Found

Symptoms:

[ERROR] Python interpreter not found
[ERROR] /usr/bin/python3: No such file or directory

Solutions:

Install Python 3.8+

# Ubuntu/Debian
sudo apt update && sudo apt install python3

# CentOS/RHEL
sudo yum install python3

# Alpine (Docker)
apk add python3

Configure NZBGet Python Path

Settings → Extension Scripts → Python Command
# Set to: python3
# Or full path: /usr/bin/python3

⚙️ Configuration Issues

Settings Not Saving

Symptoms:

  • Configuration changes revert after restart
  • Dropdown selections don't persist
  • Settings appear reset to defaults

Solutions:

Check NZBGet Configuration Permissions

# Verify config file is writable
ls -la /path/to/nzbget/nzbget.conf
# Should be writable by nzbget user

Clear Browser Cache

  1. Clear browser cache completely
  2. Hard refresh NZBGet interface (Ctrl+F5)
  3. Try different browser to isolate caching issues

Restart NZBGet After Changes

Always restart NZBGet after configuration changes to ensure they persist.

Invalid Configuration Values

Symptoms:

[ERROR] Invalid configuration value for VideoSizeThreshold
[WARNING] Configuration validation failed

Solutions:

Use Valid Number Ranges

Video Size Threshold: 1-10000 (MB)
Audio Size Threshold: 1-1000 (MB)

Check Extension Lists

# Valid video extensions (with dots)
.mkv,.mp4,.avi,.mov

# Invalid (no dots)
mkv,mp4,avi,mov

🔍 Detection Issues

Sample Files Not Being Removed

Symptoms:

  • Sample files remain after processing
  • Sample directories still present
  • Debug logs show no detection

Diagnostic Steps:

Enable Debug and Test

1. Set Debug: Yes
2. Process a download with known samples
3. Check logs for detection attempts
4. Look for pattern matching results

Common Sample Files Missed

# These might be missed with default settings:
preview.mkv          # No "sample" in name
trailer_rip.mp4      # Different pattern
SAMPLE_MOVIE.avi     # Uppercase, might need pattern adjustment
movie-rip.mkv        # Size-based only

Solutions:

Adjust Size Thresholds

# If samples are larger than threshold
Video Size Threshold: 300 (increase from 150)
Audio Size Threshold: 5 (increase from 2)

Review File Patterns

Enable debug to see pattern matching:

[DEBUG] Pattern check: 'sample' not found in 'preview.mkv'
[DEBUG] Size check: 45MB below threshold, would remove
[DEBUG] Result: Not removed (no pattern match)

Custom Pattern Solutions

For files like preview.mkv, consider if they should be removed based on size alone.

Legitimate Files Being Removed

Symptoms:

  • Important files deleted
  • Media files missing from library
  • False positive detections

Emergency Recovery: Most NZBGet installations keep download files until processed by media managers. Check:

# Original download location
/downloads/intermediate/
/downloads/queue/

# Completed but not cleaned
/downloads/completed/

Prevention Solutions:

Increase Size Thresholds

# More conservative settings
Video Size Threshold: 300 (from 150)
Audio Size Threshold: 5 (from 2)

Review Pattern Matching

# Files that might falsely match "sample"
my.sample.collection.mkv  # Collection with "sample" in title
sample_rate_test.wav      # Technical audio file
resample_output.mp3       # Processed audio file

Use Test Mode

# Temporarily disable removal
Remove Files: No
Remove Directories: No
Debug: Yes

# Review what WOULD be removed

📁 Directory Issues

Permission Errors on Directory Removal

Symptoms:

[ERROR] Cannot remove directory: Permission denied
[ERROR] Directory not empty: /path/to/sample/

Solutions:

Check Directory Permissions

# List directory permissions
ls -lad /path/to/download/directory/
# Should be writable by nzbget user

Files in Use

# Check for processes using files
lsof +D /path/to/download/directory/
# Kill processes if safe to do so

Force Directory Removal

Directory might contain hidden files or read-only files:

# Manual cleanup (use carefully!)
sudo rm -rf /path/to/sample/directory/

Nested Directory Issues

Symptoms:

  • Some sample directories remain
  • Partial directory cleanup
  • Deep nested samples not found

Solutions:

Check Directory Depth

RemoveSamples processes directories recursively, but very deep nesting might cause issues:

# Problematic structure
Movie/
└── Extras/
    └── Behind_Scenes/
        └── samples/          # Deep nesting
            └── preview.mkv

Debug Deep Directories

Enable debug to see processing:

[DEBUG] Processing directory: /downloads/Movie/Extras/Behind_Scenes/
[DEBUG] Found subdirectory: samples
[DEBUG] Directory pattern match: 'samples' matches sample pattern

🔄 Script Execution Issues

Extension Not Running

Symptoms:

  • No log entries from RemoveSamples
  • Downloads complete but no processing
  • Extension appears configured but inactive

Solutions:

Check Category Assignment

Settings → Categories → [Your Category] → ExtensionScripts
# Verify RemoveSamples is selected

Verify Script Order

# Correct order
ExtensionScripts: FakeDetector, RemoveSamples, Clean

# Incorrect (RemoveSamples missing)
ExtensionScripts: FakeDetector, Clean

Check Download Status

RemoveSamples only runs on successful downloads:

# Required for execution
PAR Status: SUCCESS or NONE
Unpack Status: SUCCESS or NONE
Download Status: SUCCESS

Script Timeout Issues

Symptoms:

[WARNING] Extension script timeout
[ERROR] Script execution aborted

Solutions:

Increase Script Timeout

Settings → Extension Scripts → Script Timeout
# Increase from default (10 minutes) to 20-30 minutes

Optimize Performance

# For large downloads, consider
Video Size Threshold: 500  # Higher threshold = fewer checks
Audio Size Threshold: 10   # Higher threshold = fewer checks

🐍 Python-Specific Issues

Module Import Errors

Symptoms:

[ERROR] ModuleNotFoundError: No module named 'json'
[ERROR] ImportError: cannot import name 'os'

Solutions:

Verify Python Installation

# Test basic Python functionality
python3 -c "import os, sys, json, re; print('Python OK')"

Check Python Version

# RemoveSamples requires Python 3.8+
python3 --version

Reinstall Python (if needed)

# Ubuntu/Debian
sudo apt remove python3 && sudo apt install python3

# Or use alternative Python
sudo apt install python3.9

Character Encoding Issues

Symptoms:

[ERROR] UnicodeDecodeError: 'utf-8' codec can't decode byte
[WARNING] File path encoding error

Solutions:

Check Filesystem Encoding

# Verify locale settings
locale
# Should show UTF-8 encoding

Set Environment Variables

# In NZBGet configuration or system
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

📊 Performance Issues

Slow Processing

Symptoms:

  • Extension takes very long to complete
  • High CPU usage during processing
  • Downloads appear stuck in post-processing

Solutions:

Optimize Configuration

# Reduce pattern complexity (fewer checks)
Video Extensions: .mkv,.mp4,.avi  # Minimal list
Audio Extensions: .mp3,.flac      # Essential only

Check System Resources

# Monitor during processing
top -p $(pgrep python3)
iostat -x 1    # Disk I/O

Large Download Optimization

# For very large downloads (>50GB)
Video Size Threshold: 1000  # Skip most size checks
Audio Size Threshold: 100   # Skip most audio checks

🔗 Integration Issues

Media Manager Not Seeing Changes

Symptoms:

  • Sonarr/Radarr still shows sample files
  • Media manager doesn't detect cleanup
  • Import issues persist

Solutions:

Check Processing Order

# Ensure RemoveSamples runs BEFORE media manager processing
ExtensionScripts: RemoveSamples  # Must be first or early
PostScript: (empty)              # Media managers use API calls

Verify Path Mapping

# Ensure paths match between NZBGet and media manager
NZBGet:  /downloads/completed/movies/
Radarr:  /downloads/completed/movies/  # Must match exactly

Force Media Manager Refresh

After RemoveSamples runs, trigger manual refresh in media manager.

🆘 Getting Additional Help

Collect Debug Information

Before reporting issues, collect this information:

System Information

# Operating system
uname -a

# Python version
python3 --version

# NZBGet version
nzbget --version

Extension Information

# Check extension files
ls -la /path/to/scripts/RemoveSamples/

# Verify manifest
cat /path/to/scripts/RemoveSamples/manifest.json

Log Samples

# Enable debug mode and collect logs
Settings → Extension Manager → RemoveSamples → Debug: Yes
# Process a test download
# Copy relevant log entries from Settings → Logging → Messages

Where to Get Help

GitHub Issues

Best for: Bug reports, feature requests, technical problems URL: https://github.com/Anunnaki-Astronaut/RemoveSamples-NZBGet/issues

Include in your issue:

  • System information (OS, Python version, NZBGet version)
  • Extension configuration settings
  • Debug logs showing the problem
  • Steps to reproduce the issue

GitHub Discussions

Best for: General questions, configuration help, workflow advice URL: https://github.com/Anunnaki-Astronaut/RemoveSamples-NZBGet/discussions

Security Issues

For: Security vulnerabilities, sensitive bugs Contact: [email protected]

Creating Effective Bug Reports

Include This Information

  1. Clear description of the problem
  2. Steps to reproduce the issue
  3. Expected behavior vs actual behavior
  4. System environment (OS, versions)
  5. Configuration settings (screenshot or text)
  6. Debug logs showing the problem
  7. Sample file names that trigger the issue (if relevant)

Example Bug Report Template

**Problem Description:**
Sample files are not being removed despite matching patterns.

**System Information:**
- OS: Ubuntu 22.04
- NZBGet: 21.1
- Python: 3.10.6
- RemoveSamples: 1.0.0

**Configuration:**
- Remove Files: Yes
- Video Size Threshold: 150
- Debug: Yes

**Steps to Reproduce:**
1. Download contains file: movie.sample.mkv (45MB)
2. Extension runs during post-processing
3. File remains after processing

**Debug Logs:**
[DEBUG] RemoveSamples: Checking file: movie.sample.mkv
[DEBUG] RemoveSamples: Pattern check: 'sample' found
[DEBUG] RemoveSamples: Size check: 45MB < 150MB threshold
[INFO] RemoveSamples: Should remove but file still exists

**Expected Behavior:**
File should be deleted.

**Actual Behavior:**
File remains in download directory.

Still having issues? → FAQ | GitHub Issues
Need configuration help? → Configuration Reference