Troubleshooting
Common issues and solutions for Plexarr V2.1.
General Issues
| Issue | Solution |
|---|---|
| Screen stream is black | Ensure a graphical session is active. On headless servers, install a dummy X display (xvfb). |
| Client shows Offline | Check firewall with sudo ufw allow 8080/tcp. Verify with curl http://server-ip:8080/health. |
| qBittorrent add fails | Verify Web UI is enabled and credentials match config. Check /api/qb/categories. |
| Auto sort misidentifies anime | Enable auto_sort.prefer_anime and select anime media type in the upload panel. |
| TMDB search returns nothing | Verify your TMDB API key is active. Keys may take a few minutes to propagate after creation. |
| Discord webhooks not firing | Verify the webhook URL is correct. Test with curl -X POST -H "Content-Type: application/json" -d '{"content":"test"}' URL. |
| Prometheus metrics empty | Ensure prometheus.enabled is true. Visit /prometheus/metrics directly. |
| File upload too large | Increase uploads.max_size_mb in config. Check Flask/WSGI limits if using a reverse proxy. |
| Phone cannot connect | Verify phone and server are on same WiFi subnet. Check router isolation settings. |
| FFmpeg not found | Install with sudo apt install ffmpeg. Set correct path in ffmpeg.path. |
| VPN not working | Verify windscribe-cli is installed and logged in. Check vpn.cli_path. |
| Cloudflare sites fail | Install cloudscraper. Enable cloudflare_solver.enabled. |
| Rapidgator free fails | Rapidgator free requires captcha. Use premium API or switch to torrents. |
| SABnzbd queue empty | Verify SABnzbd is running and API key is correct. Check sabnzbd.host includes /sabnzbd path. |
| NZBGeek search returns no results | Verify nzbgeek.api_key is valid. Check category spelling. |
| Watch folder not processing files | Verify watch_folder.enabled is true and the directory exists. Check server logs for permission errors. The watcher only processes files that appear after it starts; restart the watcher to re-scan. |
| Files mis-categorized | Use /api/naming/detect to see how Plexarr parsed the filename. Add custom variations to naming.variations if needed. Enable auto_sort.prefer_anime for ambiguous anime titles. |
| WiFi upload fails | Check /api/upload/wifi/status for size limits and allowed extensions. Ensure the staging directory exists and is writable. Verify server and client are on the same subnet. |
| WiFi upload returns 400 | Ensure the file extension is in the allowed list. Check uploads.max_size_mb in config. Try uploading a single file first to isolate batch issues. |
Connection & Network
tips_and_updates LAN Quick Checks
1. Check server is bound to 0.0.0.0 not 127.0.0.1.
2. Verify firewall: sudo ufw status or sudo iptables -L.
3. Test with curl http://server-ip:8080/health from another machine.
4. If using a VPN, ensure the VPN interface is included in binding.
Performance
- Screen stream uses significant CPU. Keep it disabled unless needed.
- Batch queue over 20 items may slow down the UI refresh rate.
- FFmpeg post-processing on large files can take minutes. Monitor via the web UI.
- Cloudflare solver adds latency. Only enable for sites that need it.
Logs
Enable verbose logging in Settings or set server.verbose to true in config.json. Logs are printed to the terminal and optionally to a file if configured.
tail -f plexarr.log