Troubleshooting index
CloudStream Not Working? Every Error and How to Fix It
Table of Contents
ShowHide
The 60-second fix list
Before you troubleshoot anything specific, run through these. They fix a surprising share of everything reported.
- Update your extensions. Settings → Extensions → Update all. This alone fixes most playback complaints.
- Update the app. Check whether you are on the current stable build.
- Try a different provider. One dead source does not mean they are all dead. Back out and pick another.
- Try a different link. Within a title, several servers are usually listed. The first one failing is normal.
- Restart the app. Fully close it and reopen. Clears stuck sessions.
- Clear the cache. Settings → Apps → CloudStream → Storage → Clear cache. Safe — it keeps your library and settings.
If none of that helps, find your exact symptom below.
Start here — find your problem
| What you are seeing | Most likely cause | Fix |
|---|---|---|
| “No links found” when you press play | Outdated or broken extension | No links found |
| Home screen is completely empty | No extensions installed — this is normal | Empty home screen |
| Repository will not add | Wrong URL type, or repo is dead | Repository won’t add |
| “App not installed” during install | Wrong APK build or signature clash | App not installed |
| Video buffers forever or shows black | Codec or bandwidth issue | Buffering and black screen |
| Extensions vanished after an update | Plugin system changed | Extensions disappeared |
| Downloads stuck at 0% or failing | Permission or storage problem | Downloads not working |
| App crashes on TV or Firestick | Low memory, too many extensions | Crashing on TV |
| Cast icon missing or casting fails | Network or stream format | Chromecast not working |
| Subtitles ahead of or behind the audio | Timing mismatch in the subtitle file | Subtitles out of sync |
Which layer is actually broken?
This is the single most useful troubleshooting skill for this app, and almost nobody explains it. CloudStream has four layers, and knowing which one failed tells you exactly what to do.
| Layer | What it does | How you know it is the problem |
|---|---|---|
| 1. The app | Player, downloader, plugin loader | Crashes, interface freezes, install failures |
| 2. The repository | Lists available extensions | Will not add, or the extension list is empty |
| 3. The extension | Reads one specific website | One provider fails, others work fine |
| 4. The source | The website itself | All extensions for that site fail, everywhere |
A quick diagnostic
- Does the app open and navigate normally? → the app is fine, move down.
- Does the repository load its extension list? → the repository is fine, move down.
- Do other providers return results for the same title? → the app, repo and your connection are all fine. One extension broke.
- Do all providers fail on everything? → check your internet, then check whether you have any working extensions installed at all.
Why this matters: roughly nine out of ten reported “CloudStream is broken” cases are a single failed extension at layer 3. The fix is to update extensions or switch provider — not to reinstall the app, and definitely not to wipe your data.
Playback errors
“No links found” or nothing plays
The single most reported issue.
- Update all extensions first.
- Try a different provider for the same title.
- Check whether that repository is still maintained.
- Some sources are region-blocked, so a VPN may change the outcome.
- Restart the app to clear a stale session.
Full guide: No links found fix
Video buffers constantly or plays as a black screen
- Choose a lower quality in the player’s gear menu.
- Pick a different server link for the same title.
- Turn on software decoding in player settings. This is the fix for most black-screen cases on older devices.
- Try handing the stream to VLC or MX Player instead.
Full guide: Buffering and black screen
Video plays but there is no sound
- Open the player’s gear menu → Audio and check which track is selected. Some sources default to a track your device cannot decode.
- Switch to a different audio track if one is available.
- Turn on software decoding.
- Try a different source link — audio problems are usually specific to one file.
Subtitles are ahead of or behind the audio
- Use the offset control in the player’s subtitle menu. It has a live preview.
- Positive values delay the subtitles, negative values move them earlier.
- If a subtitle file is unusable, search for a different one inside the player.
Full guide: Subtitles out of sync
Playback starts then stops after a few seconds
- Usually a link that expired between resolution and playback. Back out and pick another server.
- Check whether your connection dropped.
- Lower the quality — some sources throttle high bitrates.
Setup and content errors
Home screen is completely empty
This is not a bug. CloudStream ships with no content of its own.
- Add a repository: Settings → Extensions → Add repository.
- Install at least one extension from it.
- Go back to the home screen and pick a provider from the floating button.
Full guides: Empty home screen · Repositories
The repository will not add
- Make sure the URL points to the raw JSON file, not a web page. Raw links contain raw.githubusercontent.com or /raw/.
- Use the shortcode instead — it removes typing mistakes entirely.
- Open the URL in a browser to confirm the file still exists.
- Some networks and DNS providers block GitHub raw content. Switch from Wi-Fi to mobile data to test.
Full guide: Repository won’t add
The repository adds but shows no extensions
- The repository is most likely inactive or has moved.
- Check its source page for recent activity.
- Remove it and use an active alternative from the repository list.
Extensions disappeared after updating the app
- Plugin system changes between major versions can reset installed extensions.
- Your repositories should still be listed — reinstall the extensions from them.
- A backup prevents this being annoying: backup and restore.
Full guide: Extensions disappeared
Search is very slow
- Too many installed providers, especially dead ones. The app waits for each to time out.
- Remove extensions that have been failing for weeks.
- Set provider priority so reliable sources are checked first.
Install errors
“App not installed” or parse error
- The download was incomplete or damaged. Delete it and download again.
- You may have the wrong APK build for your processor. Try the universal build.
- An existing CloudStream install with a different signature is blocking it. Uninstall it first, after backing up.
- Your Android version is below 5.0.
- Not enough storage.
Full guides: App not installed · Which APK build do I need?
Play Protect blocks the install
- Expected for any app not distributed through the Play Store. It is a warning about the source, not a scan result.
- Tap More details, then Install anyway.
- Verify the file yourself instead: how to verify your download.
No install prompt appears when you tap the APK
- Unknown-source permission is per app. Enabling it for Chrome does not enable it for your file manager.
- Go to Settings → Security & privacy → Install unknown apps, and enable it for whichever app you are opening the file from.
The file downloaded with a .bin or .zip extension
- Some browsers rename APK files. Rename it back to .apk with a file manager.
- Or download using a different browser.
Download errors
These are about the app’s built-in downloader, not about downloading the APK.
Downloads stuck at 0% or failing immediately
- Confirm storage permission is granted in Android’s app settings.
- Free up space on your device.
- The source may not support downloading. Try a different provider.
- Change the download folder — some devices block writes to certain paths.
Full guide: Downloads not working
Downloads finish but the file will not play
- The file may be incomplete despite showing as finished. Delete and re-download.
- Try opening it in VLC, which handles more formats than most default players.
Downloaded files disappeared
- Check whether the download folder changed after an app update.
- Some cleaner apps delete media from non-standard folders. Exclude your download folder from them.
The download button is missing
- Not every source supports downloading. Live content never does.
- Try a different provider for the same title.
Device-specific errors
Android TV or Firestick
- Crashes or freezes — low-memory devices struggle with many extensions. Remove the ones you do not use.
- Wrong layout — force TV layout in Settings → Layout.
- Stuttering playback — older Firestick models cannot handle high-bitrate 1080p. Drop the quality.
- Cannot type a repository URL — use the shortcode instead.
Full guide: Crashing on TV
PC and emulators
- App will not install in the emulator — you need the x86_64 build, not arm64-v8a.
- Playback is choppy — allocate more RAM and CPU cores to the emulator.
- Controls feel wrong — set the layout to emulator or phone rather than TV.
Full guide: CloudStream for PC
Chromecast
- Phone and Chromecast must be on the same network.
- Grant the app local network permission.
- Not every stream format can be cast. Try a different link first.
Full guide: Chromecast not working
Problems you cannot fix
Being honest about this saves people hours. Some things are not fixable from your end, and no amount of reinstalling will change them.
- A source website shut down. The extension has nothing left to read. It will not come back.
- A repository was abandoned. Its extensions will keep decaying. Replace it.
- A source is blocked in your country. A VPN may work, but that is a workaround rather than a fix.
- The extension author stopped maintaining it. Fixes only arrive if a volunteer picks it up.
- Your device is too old. Below Android 5.0, current builds simply will not run.
- Live TV and sports keep breaking. These sources change addresses constantly. Instability is normal for this category, not a fault.
- There is no iOS version. No workaround exists.
The general rule: if the app opens, the repository loads, and other providers work, then the problem is a specific source and your only real option is to use a different one.
How to report a bug properly
Reporting in the wrong place is why many reports never get answered.
If the app itself is broken — crashes, interface bugs, player faults:
- Report on the recloudstream GitHub issue tracker.
- Include your device model, Android version, app version and build type.
- Describe the steps that reproduce it.
- Search existing issues first — most common problems are already open.
If one provider is broken — no links, wrong results, missing episodes:
- Do not report this to the CloudStream core team. They do not maintain third-party extensions.
- Report it to that extension’s maintainer, on the repository’s own source page.
Before reporting anything, confirm it is not you:
- Extensions updated?
- App on the current stable build?
- Does the same title work on a different provider?
- Does it fail on a different network?
Official links: https://github.com/recloudstream/cloudstream
Frequently asked questions
Why is CloudStream not working?
In most cases a single extension broke. Update your extensions and try a different provider before assuming the app is at fault.
Why does it say “no links found”?
The extension could not pull a playable link from its source. Usually the source website changed and the extension needs updating.
Why is my home screen empty?
Because you have not installed any extensions yet. The app ships with no content — that is by design, not a bug.
Why did my extensions disappear?
An app update changed the plugin system. Your repositories are still there, so reinstall the extensions from them.
Will reinstalling the app fix my problem?
Almost never, and it wipes your library and settings. Try updating extensions first.
Do I need a VPN to fix errors?
Only for region-blocked sources. It will not fix a broken extension.
Why does the app keep crashing on my TV box?
Usually low memory combined with too many installed extensions. Remove the ones you do not use.
Is “App not installed” a virus warning?
No. It usually means the wrong APK build, a signature clash with an existing install, or not enough storage.
Why is search so slow?
The app queries every installed provider and waits for each one, including dead ones. Remove providers that have stopped working.
Where do I report a broken provider?
To that extension’s maintainer, not to the CloudStream team. They do not control third-party extensions.
How often do extensions break?
Regularly. Each one depends on a website it does not control. Keeping automatic extension updates on handles most of it.
Can I fix a dead source?
No. If the website is gone, the extension has nothing to read. Switch to a different provider.