Troubleshooting
Most playback problems come down to one of three things: the provider, the network, or the User-Agent. Here's how to find out which.
A stream won’t play
Right-click the channel (or movie / episode) and pick Test stream. The dialog tells you whether the stream is reachable.
- Reachable but won’t play - the in-app player can’t decode the codec. Open it in MPV or VLC instead. See External players.
- 403 or 401 response - your provider is blocking you based on your User-Agent. Open Settings > Network and pick a different UA preset (VLC, ExoPlayer, and MX Player cover the common cases).
- Connection failed entirely - the server is down, your network is blocking it, or the URL has changed. Check the provider’s status page or contact support.
”Couldn’t load channels - check your login”
The Xtream sign-in failed. Most common causes:
- Missing
http://orhttps://in the Server URL. Some providers send URLs without it - add it yourself. - Wrong port. Check your provider’s URL for a number after the colon (
:8080,:25461) and include it. - Expired account. Some providers return a generic error for expired accounts. Check with your provider.
- Region-locked. The provider sees your IP from a region they don’t serve.
EPG is shifted by a few hours
Your provider is sending TV listing times in their own timezone instead of UTC. Open Settings > Live TV and adjust the EPG offset until the program guide matches reality. The offset is saved per playlist.
EPG titles look like random letters
Some providers encode TV listing data in a way that looks like gibberish until decoded. The app handles this automatically. If you still see scrambled text after refreshing, it’s a provider-side issue - file an issue and include the affected channel.
Streams play but lag or buffer
- Turn on Performance mode in Settings > Display. It strips out decorative animations to free up CPU - helps a lot on older Android TV boxes and low-end devices.
- For heavy 4K or HEVC streams on Android, the built-in player is often the bottleneck. Hand off to VLC or MX Player. See External players.
- Check whether your provider limits how many streams you can run at once. Settings > Downloads shows the cap your account is allowed.
A stream works in VLC but not the in-app player (Android)
Some providers gate channels behind a specific User-Agent. The in-app player respects per-channel User-Agents on Android, but not every channel sets one correctly. Try a custom UA in Settings > Network > Custom UA - your provider can tell you which value to use.
Picture-in-picture is a black rectangle (Android)
Downloads won’t resume
Downloads pick back up from where they left off when you restart the app. If one is stuck:
- Check Settings > Downloads > Folder is set and writable. On Android, you may need to re-grant folder access.
- Cancel the stuck download and re-queue it.
- If the same download keeps failing partway through, delete the partial file and start over - some providers send mismatched file sizes that confuse the resume logic.
Start fresh
If you want to wipe everything and start over, open Settings > Danger zone > Reset everything. This clears your playlists, favorites, watch history, and cache. Downloaded files stay on disk - you can delete them manually if you don’t need them.