Troubleshooting - theweebcoders/CommercialBreaker GitHub Wiki
This guide helps you resolve common issues with CommercialBreaker & Toonami Tools.
Error: [WinError 2] The system cannot find the file specified
Solution:
- Install FFmpeg: Download from https://www.ffmpeg.org/
-
Place in Tools folder: Copy
ffmpeg.exe,ffprobe.exe,ffplay.exetoTools/directory -
Or install via package manager:
-
Windows:
choco install ffmpeg -
macOS:
brew install ffmpeg -
Linux:
sudo apt install ffmpeg
-
Windows:
Error: Various import or syntax errors
Solution:
- Ensure Python 3.11+ is installed
- Check version:
python3 --version - Use correct Python command for your system
Error: ModuleNotFoundError: No module named 'xyz'
Solution:
pip install -r requirements.txtIf you're using Cutless Mode with DizqueTV, install the official dizquetv Python API before the main requirements:
pip install -r requirements/pre_deps.txt
pip install dizquetv
pip install -r requirements.txtNote:
- This setup is for manual desktop installs
- Docker installs already include the required dependencies
S.A.R.A. (System Analysis and Reporting Assistant) is your first stop for troubleshooting. Before diving into specific issues, use S.A.R.A. to get a comprehensive analysis of your pipeline state.
Use S.A.R.A. diagnostics when:
- Something isn't working and you don't know why
- A step seems to have failed
- Channel creation produces unexpected results
- Processing appears stuck or incomplete
- You need to understand what went wrong
Panic Button: Click any page title 5 times in 2 seconds
Step 1: Open S.A.R.A. Diagnostics (Page8)
Step 2: Check Pipeline Status
- Look at the completion checklist
- Find the last successful step (✓)
- Find the failing step (✗)
- Note which step hasn't run yet (○)
Step 3: Run Full Validation
- Click "Run Full Validation" button
- Wait for results (5-30 seconds)
- Read through issues from top to bottom
Step 4: Follow Suggestions
- Start with CRITICAL issues (⊗)
- Then address ERRORs (✗)
- Review WARNINGs (⚠) as needed
- Each issue includes specific fix suggestions
Step 5: Copy Results for Help
- Click "Copy All Results" button
- Include in bug reports or support requests
"Table 'xyz' does not exist"
- Meaning: Step hasn't been run yet
- Fix: Run the step from the interface
"Platform type not set in app_data"
- Meaning: Platform selection incomplete
- Fix: Select platform on Page1 (DizqueTV, Tunarr, or ComBreakDirect)
"X episodes missing commercial break timestamps"
- Meaning: Commercial detection didn't find break points
- Fix: Re-run CommercialBreaker in normal mode (not low power)
- Note: Some episodes may not have detectable breaks
"Table 'xyz' has insufficient data"
- Meaning: Step ran but didn't process any content
- Fix: Check input folders have files, verify file naming
"Missing required columns"
- Meaning: Database schema is outdated or corrupt
- Fix: Re-run the step to rebuild table
"BLOCK_ID not found in lineup_prep_out"
- Meaning: Lineup references a bump that doesn't exist
- Fix: Re-run "Prepare Toonami Channel" to rebuild lineup
"Episode repeated in lineup"
- Meaning: Same episode appears multiple times
- Usually OK: Marathon format often repeats episodes
- Fix: Only address if unintentional
"Cutless mode active but platform is Tunarr"
- Meaning: Platform incompatibility
- Fix: Change to DizqueTV or disable cutless mode
"Multibump not followed by anime"
- Meaning: Lineup placement rule violation
- Fix: Re-run Merger to rebuild lineup
These are informational only - no action required:
- "3 versions detected" - Normal if using multiple Toonami versions
- "Cutless mode active" - Confirmation of your mode selection
- Platform and configuration confirmations
Symptoms:
○ PlatformSelection - Not run yet
○ PlexAuth - Not run yet
○ FolderMaker - Not run yet
...
Diagnosis: Pipeline hasn't been started yet
Fix:
- Go to Page1
- Select your platform
- Authenticate with Plex (if required)
- Set up folder paths
- Run "Prepare Toonami Channel"
Symptoms:
✓ ToonamiChecker - Completed successfully
✓ LineupPrep - Completed successfully
...
✗ CommercialBreaker - Failed: 15 episodes missing timestamps
○ CommercialInjector - Not run yet
Diagnosis: Commercial detection didn't find breaks in some episodes
Fix:
- Check which episodes are missing timestamps (listed in details)
- Verify episodes are actual anime (not bumps)
- Try different detection modes:
- Normal mode: Most thorough
- Fast mode: Skips silent black frame detection
- Low power mode: Only checks chapters/Plex
- For episodes without detectable breaks:
- May have different commercial break patterns
- May need manual timestamp entry
- Can skip these episodes if necessary
Symptoms:
⚠ WARNING: Cutless mode active but platform is Tunarr (unsupported)
Diagnosis: Tunarr doesn't support cutless mode
Fix:
- Option 1: Change platform to DizqueTV 1.7+ or ComBreakDirect
- Option 2: Disable cutless mode and use traditional cutting
- Note: Can't use cutless with Tunarr
Symptoms:
⚠ WARNING: Stale cutless tables detected: lineup_v2_cutless, lineup_v3_cutless
Diagnosis: Database contains tables from previous run with different mode
Fix:
- These old tables can be safely ignored
- Or delete them if you want to clean up:
DROP TABLE IF EXISTS lineup_v2_cutless; DROP TABLE IF EXISTS lineup_v3_cutless;
After running S.A.R.A. diagnostics:
- If S.A.R.A. identifies the problem: Follow its suggestions
- If issues persist: Refer to specific sections below
- If S.A.R.A. shows no issues: Problem may be outside database (files, network, etc.)
S.A.R.A. validates the database state - it doesn't check:
- Physical file existence (though some validators do sample checks)
- Network connectivity
- FFmpeg installation
- Disk space
- File permissions
For these issues, see specific troubleshooting sections below.
For large databases (many shows/episodes):
- Use "Refresh Status" for quick checks during processing
- Run "Full Validation" only when needed (after major steps)
- Full validation may take 15-30 seconds with large databases
During active processing:
- S.A.R.A. runs in background thread
- Won't interfere with other operations
- Results appear in real-time as validation progresses
Problem: Can't connect to Plex server
Solutions:
- Check Plex credentials: Verify server URL and token
- Network connectivity: Ensure Plex server is accessible
- Manual token entry: Use Plex token directly if OAuth fails
- Firewall/VPN: Check if network restrictions block access
Smart Connection Retry: CommercialBreaker automatically tries all available connection URLs for your Plex server:
- Local network URLs (fastest)
- Direct connections
- Relay URLs (fallback)
If connection fails after trying all URLs, check the application logs to see which URLs were attempted.
Problem: Connection to Plex server times out or is unreliable
Automatic Handling: CommercialBreaker includes smart connection retry logic that handles most timeout issues automatically:
- Tries local network URLs first (192.168.x.x, 10.x.x.x)
- Falls back to direct public IPs
- Uses Plex relay URLs as last resort
- Logs all connection attempts for debugging
Manual Solutions (if automatic retry doesn't resolve):
- Check network stability: Ensure consistent connection to your network
- Plex server status: Verify Plex server is running and responsive
- Router/firewall: Ensure ports are properly forwarded for direct connections
- Relay URL issues: If only relay works, consider port forwarding for better performance
- Review logs: Check console output to see which connection URLs were tried
Understanding Connection Priority:
- Local URLs (best): Direct connection on same network, fastest response
- Direct URLs (good): Public IP with port forwarding, reliable
- Relay URLs (fallback): Routed through Plex servers, can timeout under load
Problem: Selected library doesn't appear or is empty
Solutions:
- Refresh Plex libraries: Scan for new content
- Check file naming: Ensure files follow naming conventions
- Verify permissions: Ensure Plex can access file locations
- Library type: Confirm you're selecting the correct library type (TV Shows)
Problem: Detection phase finds no timestamps
Causes & Solutions:
No Chapter Markers:
- Use sources with embedded chapter markers for best results
- Consider "Low Power Mode" if no chapters available
Silent/Black Frame Detection Fails:
- Check audio levels aren't too low/high
- Adjust detection thresholds in config:
SILENCE_THRESHOLD = -50.0 # Try -40.0 or -60.0 BLACK_FRAME_THRESHOLD = 0.1 # Try 0.05 or 0.2
No Plex Timestamps:
- Ensure Plex Pass subscription active
- Enable "Skip Intro" feature in Plex
- Run "Get Plex Timestamps" step
Problem: Commercial detection runs for hours/days
Solutions by Priority:
- Use Chapter Markers: 80,000x faster than frame analysis
- Filter Shows First: Use ToonamiTools to process only needed shows
- Enable Fast Mode: Reduces detection methods used
- Use Low Power Mode: Chapter markers and Plex timestamps only
- Process in Batches: Select specific shows/episodes instead of entire library
Problem: Some episodes fail to cut properly
Common Issues:
Corrupted Files:
- Check source file integrity
- Re-download or re-encode problematic files
Insufficient Disk Space:
- Ensure adequate free space (2-3x source file size)
- Clean up temporary files in working directory
Timestamp Accuracy:
- Use Manual Timestamp Editor
- Fine-tune break points manually
Problem: Can't create channel in DizqueTV
Solutions:
- Verify URL: Check DizqueTV server address and port
- API Access: Ensure DizqueTV API is accessible
- Version Compatibility: Use DizqueTV 1.7+ for Cutless Mode
- Network Issues: Check firewall and network connectivity
Problem: Channel creation fails with Tunarr
Solutions:
- Check Tunarr Status: Ensure Tunarr server is running
- Web Interface Access: Verify you can access Tunarr web UI
- Version Requirements: Ensure compatible Tunarr version
- Cutless Mode: Note that Cutless Mode requires DizqueTV
Problem: Commercial breaks not properly added
Solutions:
- DizqueTV Only: Flex injection only works with DizqueTV
- Post-Channel Creation: Run flex injection after channel creation
- API Permissions: Ensure DizqueTV API access is working
- Channel Exists: Verify channel was created successfully first
Problem: A ComBreakDirect channel that was working has stopped auto-extending — Plex's guide eventually runs out and the channel loops back to the beginning.
Diagnosis: The LineupExtender disables itself after MAX_CONSECUTIVE_FAILURES (3) consecutive extension failures. Check _infinite_meta in channels.json:
# Native install
cat combreak_direct_data/channels.json | jq '.channels."<num>"._infinite_meta'
# Docker
cat /app/working/combreak_direct/channels.json | jq '.channels."<num>"._infinite_meta'Look at enabled, consecutive_failures, and last_extension_at.
Solutions:
-
enabled: false— the watchdog gave up. Check ComBreakDirect logs for the failure reason (search for[LINEUP_EXTENDER]and[FACTORY_FLOOR] Cannot spawn). Common causes:- Source media missing or unmounted (ShowScheduler couldn't find episodes)
-
last_used_episode_blocktable corrupted (drop the table and seed will repopulate on next channel creation) - Disk space below the configured threshold (default 2 GiB free required in the storage partition)
-
consecutive_failures > 0— the watchdog is still trying but has hit transient errors. Inspect logs sincelast_extension_atfor the underlying cause (disk space, ShowScheduler errors, mapping data missing). Each retry happens 5 minutes after the prior failure. -
Force a re-arm — recreate the channel via Page 6 (POST /channels overwrites the existing channel and respawns a fresh LineupExtender with
enabled=trueand zero failures).
Problem: run_server.py exits during boot with a traceback from CommercialBreakRenderer._load_existing_breaks, complaining about a missing _seg_*.mkv file. Absolution's thread fallback then takes over and writes to a different storage path, causing apparent "channel disappeared" symptoms.
Cause: A stale temp segment file in _pre_rendered_breaks/ got cleaned up between listdir() and stat(). Hardened in CommercialBreakRenderer.py to skip vanished files instead of crashing, but you can also clean up manually.
Solutions:
-
Stop the container, then
find _pre_rendered_breaks -name '*_seg_*.mkv' -delete(orrm -rf _pre_rendered_breaksfor a full reset — the renderer will repopulate it from the lineup). - Restart. The subprocess will scan the (now clean) directory and start cleanly.
-
Check for two ComBreakDirect instances: in Docker,
start.shlaunchesrun_server.pyas a subprocess; Absolution will only spawn its own thread fallback if the subprocess port (8083) isn't responding. If you see bothpython3 run_server.pyANDpython3 main.py --webuiAND the thread fallback was triggered, the subprocess died and you have a path mismatch (subprocess uses/app/combreak_direct_data/, thread fallback uses/app/working/combreak_direct/).
- Ensure you have an active internet connection (validator checks Wikipedia).
- Use the exact network name Wikipedia uses (e.g., “Cartoon Network”, “Disney Channel”).
- Multi‑word names are supported; you do not need underscores.
- Try again later — Wikipedia may rate‑limit requests in some environments.
- TOM/Absolution must restart to fully apply the change. “Apply & Restart” will re‑exec the app; if that fails (restricted environment), restart the process manually.
Problem: Anime not detected by ToonamiChecker
Solutions:
-
Check Naming Format: Must be
Show Name - S##E## - Title - Show Name Matching: Verify show names match expected format
- Manual Addition: Use Manual Show Adder
- Database Update: Show may not be in Toonami database
Problem: Bump files not recognized during lineup creation
Solutions:
- Follow Naming Convention: Use exact bump naming format
- Show Name Consistency: Ensure bump show names match episode show names
- Version Numbers: Include Toonami version in bump names
- Placement Keywords: Use correct transition keywords
Problem: Application uses excessive RAM
Solutions:
- Process Smaller Batches: Select fewer files at once
- Close Other Applications: Free up system memory
- Increase Virtual Memory: Adjust system swap/page file settings
- Use Cutless Mode: Reduces memory requirements
Problem: Operations take much longer than expected
Solutions:
- SSD Storage: Use solid-state drives for working directory
- Local Processing: Avoid network drives for intensive operations
- Hardware Upgrade: Consider faster CPU for encoding operations
- Background Tasks: Minimize other system activities
Problem: SQLite database errors or crashes
Solutions:
-
Delete Database: Remove
Toonami.dband restart - Backup Regularly: Keep copies of working database
- Check Disk Space: Ensure adequate storage available
- Rebuild Database: Re-run content preparation steps
Problem: Application behavior seems erratic
Solutions:
- Clear Cache: Delete temporary files in working directory
- Reset Configuration: Restart configuration process
- Fresh Start: Clear database and reconfigure from scratch
Problem: Docker container fails to launch
Solutions:
-
Check Environment Variables: Verify
.envfile configuration - Volume Mounts: Ensure paths exist and are accessible
- Port Conflicts: Verify port 8081 is available
- Docker Resources: Allocate sufficient memory/CPU to Docker
Problem: Files not accessible inside container
Solutions:
- Path Format: Use absolute paths in docker-compose.yml
- Permissions: Ensure Docker has access to mounted directories
- Path Existence: Verify all mounted paths exist on host
- SELinux/Security: Check if security policies block access
- Check Library Type: Must be TV Shows library
- Verify Content: Ensure anime files are present and named correctly
- Plex Scan: Force library refresh in Plex
- Install FFmpeg: See FFmpeg installation instructions
- Update Config: Verify FFmpeg path in config.py
- Environment PATH: Ensure FFmpeg is in system PATH
- Choose Platform: Select either DizqueTV or Tunarr in interface
- Version Check: Ensure compatible platform version
- Network Access: Verify platform server is reachable
- Use DizqueTV 1.7+: Update your DizqueTV server to a compatible version
- Or Use Traditional: Disable Cutless Mode for standard cutting
If issues persist:
- Check FAQ: Review FAQ.md for additional solutions
- Discord Community: Join our Discord
- GitHub Issues: Create an issue with detailed error information
- Log Files: Include relevant log files and error messages
- ChatGPT: Give all these documents and a link to the repo to ChatGPT for assistance
When reporting issues, provide:
- Operating system and version
- Python version
- Error messages (full text)
- Steps to reproduce
- File naming examples
- Configuration settings (without sensitive data)
- Use Chapter Markers: Source content with embedded chapters
- Consistent Naming: Follow naming conventions exactly
- Regular Backups: Save working database and configurations
- Test Small: Start with a few episodes before processing large libraries
- Monitor Resources: Ensure adequate disk space and memory
- Update Regularly: Keep software and dependencies current
- SSD Storage: Use fast storage for working directories
- Local Processing: Avoid network drives during processing
- Batch Intelligently: Process similar content together
- Clean Regularly: Remove temporary files and unused data