Skip to content
Closed Alpha
FluxPlay is currently in Closed Alpha. This documentation is a work in progress and may be incomplete or out of date. Features, UI, and APIs are subject to change without notice. For access inquiries, please contact [email protected].
TROUBLESHOOTING
Diagnose and resolve common FluxPlay issues. Start with the quick checklist, then find your specific problem below.
Quick Diagnostic Checklist
Run through these checks before diving into specific issues:
Is FluxPlay running? Check that the server process is active
Can you access the web interface? Try http://localhost:5171
Are all services healthy? Check Settings → System
Is the database connected? Status page shows connectivity
Is FFmpeg available? Required for playback
Are media folders accessible? Check file permissions
Is there enough disk space? Transcoding needs temp storage
Check the logs - Most issues leave clues in Settings → Logs
Installation Issues
Database Connection Failed
Symptoms:
Server won't start"Database connection failed" error"Unable to connect to PostgreSQL"
PostgreSQL not runningStart PostgreSQL service (systemctl status postgresql)
Wrong connection settingsVerify host, port (5432), username, and password
Database doesn't existCreate database manually and grant permissions
Firewall blockingOpen port 5432 and check pg_hba.conf
FFmpeg Not Found
Symptoms:
"FFmpeg not found" on startupPlayback fails for all mediaTranscoding unavailable
FFmpeg not installedInstall via package manager or ffmpeg.org
Not in system PATHAdd FFmpeg location to PATH or specify full path
Wrong versionRequires FFmpeg 4.4+ (check with ffmpeg -version)
Port Already in Use
Symptoms:
"Address already in use" errorServer won't start
Another instance runningStop existing FluxPlay processes
Another app using portFind with lsof -i :5171 or netstat -ano
Crash left port boundWait 1 minute or restart machine
Library & Scanning Issues
Media Not Showing
- Unsupported formatConvert to MKV, MP4, AVI, MOV
- Wrong folder structureMovies/Name (Year)/file.mkv
- Permission issuesVerify read access to folders
- Path not addedAdd folder in Settings → Libraries
- Scan incompleteWait for scan to finish or rescan
Wrong Metadata
- Ambiguous namesAdd year: Movie Name (2023).mkv
- Wrong matchEdit → Identify → Search correct title
- Provider issuesCheck Settings → Metadata providers
- Missing infoRefresh metadata for affected items
Scan Stuck or Slow
Very large library
First scans are slower; subsequent scans faster. Scan one library at a time.
Network storage
NAS/network drives have latency. Ensure stable connection.
Corrupt files
Check logs to identify problematic files. Move or delete corrupt ones.
Low resources
Close other apps during initial scan. Scanning uses CPU/RAM.
Playback Issues
| Problem | Likely Cause | Solution |
|---|---|---|
| Video won't play | Unsupported codec | Enable transcoding in Settings → Playback |
| Black screen | File permissions changed | Verify FluxPlay can access the file |
| Constant buffering | Insufficient bandwidth | Reduce quality or enable lower bitrate transcoding |
| Buffering (server) | Transcoding can't keep up | Enable hardware acceleration |
| No audio | Unsupported audio codec | Enable audio transcoding (DTS/TrueHD often need it) |
| Wrong audio | Wrong track selected | Click audio icon and select correct track |
| No subtitles | Not enabled | Click subtitle icon and select track |
| PGS subtitles missing | Image subs need burn-in | Enable subtitle burning in settings |
| HDR washed out | Transcoding stripping HDR | Enable HDR tone mapping or use direct play |
Transcoding Issues
High CPU Usage
- • Normal for software transcoding
- → Enable hardware acceleration
- • Too many streams
- → Limit concurrent transcodes
- • Transcoding when not needed
- → Prefer direct play settings
Hardware Accel Not Working
- • Drivers not installed
- → Install latest GPU drivers
- • Not enabled in settings
- → Settings → Transcoding → Enable
- • Unsupported GPU
- → Check GPU compatibility
- • Docker GPU passthrough
- → Add --gpus all or --device /dev/dri
Quality Problems
- • Video looks blocky
- → Increase transcoding bitrate
- • Wrong colors
- → Enable proper tone mapping
- • Artifacts in video
- → Use "Quality" preset vs "Speed"
Download Issues
Downloads Failing
Source unavailable→ Content may be removed. Try different source.
yt-dlp outdated→ Update via Settings → Downloads → Update yt-dlp
Network/geo-block→ Check connection. Use VPN if geo-blocked.
Disk full→ Check download folder space
Invalid URL→ Verify URL format is correct
Missing from Library
Download folder not in library→ Add download folder to a library
Scan needed→ Trigger library scan or enable auto-scan
Wrong format→ Check download wasn't audio-only
Authentication Issues
Can't Log In
- Check caps lock and typos
- Account locked? Wait 15 min or contact admin
- Clear browser cookies/cache
- Check server time is correct
MFA Not Working
- Sync phone time automatically
- Enter code quickly (30 sec window)
- Don't include spaces in code
- Use backup codes if available
SSO Problems
- Verify SSO configuration with admin
- Check callback URL is correct
- Test other SSO apps work
- Account may need SSO linking
Locked Out Completely
- Use backup codes from MFA setup
- Contact admin for password reset
- Admin can disable MFA temporarily
- Server recovery mode for sole admin
Network Issues
Can't Access Remotely
Port forwarding not set
Forward port 5171 on router to server
Firewall blocking
Allow 5171 through Windows Firewall/iptables
Dynamic IP
Use dynamic DNS (DuckDNS, No-IP)
ISP blocking
Contact ISP or use Cloudflare Tunnel
Wrong address
Use public IP/domain externally
Connection timeouts
Check server load, use wired connection
Error Messages Quick Reference
| Error | Quick Fix |
|---|---|
| Database connection failed | Check PostgreSQL service and connection settings |
| FFmpeg not found | Install FFmpeg and add to system PATH |
| Port already in use | Change port or stop conflicting service |
| Playback error | Enable transcoding |
| Transcode failed | Check logs, verify FFmpeg installation |
| Access denied | Check user permissions and library sharing |
| Invalid credentials | Reset password or wait for lockout to expire |
| Invalid MFA code | Sync device time automatically |
| Connection timeout | Check network, server status, and firewall |
Still Need Help?
When reporting issues, include this information for faster help:
- FluxPlay version (Settings → System → About)
- Operating system and version
- Installation method (Docker/manual)
- Steps that led to the problem
- Exact error messages
- What you expected to happen
- Troubleshooting already tried
- Relevant logs (remove personal info)