A video will not play
- Try a second public video. If only one fails, it may be removed, private, region-restricted, or otherwise unavailable. For age-restricted or members-only videos, see below.
- Check your connection and restart OpenTubeX.
- Update the app. YouTube changes can break extraction in older versions.
- If you changed playback or provider settings, review them under Playback and Advanced. Try returning the affected option to its default and retry the same video.
- Check existing issues for the same error before opening a report.
For buffering, try a lower quality in the player. With the Local API, Always use backup media server in Settings → Advanced can help when YouTube’s assigned server is slow. If you use a proxy or an alternative provider, check whether the problem also happens without that configuration. Note which setting made a difference.
If search and channel pages work but videos fail, OpenTubeX already tries the other stream extraction method by default. The error message also offers Retry with built-in extraction or Retry with yt-dlp extraction. Include the failing method in your report. To keep a recovery error on screen instead of a brief notification, turn on Settings → Playback → Pause on Stream Recovery.
If the error says YouTube has blocked your IP address, switch to a different VPN or proxy, or try another provider.
Age-restricted or members-only videos
Age-restricted videos need an age-verified Google account. Members-only videos need a Google account with an active membership to the channel. On desktop and Android, configure cookies under Settings → Advanced → yt-dlp Cookies, then choose Try with configured cookies on the video. Using yt-dlp with a Google account can lead to restrictions on that account.
Imports or subscriptions look incomplete
- Check the active profile and try All Channels.
- Review feed filters and refresh the subscription feed.
- For an import, check the success or skipped-item message and confirm that you used a supported format.
- Keep the original export so you can retry or investigate missing entries.
An imported channel list does not instantly contain every video. Refreshing the feed needs a working connection. Do not clear your data as a first troubleshooting step.
Repair imported history
If imported history entries have missing titles, channels, or publication dates, incorrect durations, or incorrect LIVE labels:
- Open History and choose Repair History. On narrow screens, the button reads Repair.
- Review the description, then choose Start repair.
- Keep a working internet connection and let the repair run. Large histories can take time; failed requests are retried automatically.
- Check the repaired and failed counts, then review the affected entries.
Review what Repair History changes, then select Start repair.
Repair fetches video details while preserving watch progress and watched status. Deleted or private videos may remain incomplete. It cannot recover watch events that were absent from your export. Keep the original export while investigating missing data.
Downloads fail or saved files are missing
Check the chosen download folder, storage permission, and free space. Moving or deleting a saved file outside OpenTubeX can make its list entry unavailable. On desktop, a download error mentioning external tools may require updating the managed tools. Follow the download troubleshooting steps.
Android background playback stops
- Confirm that playback works with the app in the foreground.
- In OpenTubeX, check that Settings → Playback → Continue playback when the screen is locked is on.
- Open Android’s app information for OpenTubeX and review its battery/background usage settings. Allow background activity if Android has restricted it; names vary by device.
- Check notification permission if media controls are missing.
- Test again with the screen locked and note whether the problem happens on Wi-Fi, mobile data, or both.
Include your Android version and device model in a report. Desktop and Android behavior may differ.
The app will not open after installation
Check that the package matches your processor and meets the requirements on the Downloads page. Extract portable archives before running them. On Linux, check the executable permission for an AppImage. On macOS, review the first-launch instructions in the installation guide.
Before reinstalling or clearing storage, export your data if the app still opens. Clearing application data can remove your local library and settings.
Report a bug
- Search the OpenTubeX issue tracker for your error or symptoms.
- If no existing issue matches, select New issue and use the bug-report template.
- Include the OpenTubeX version, operating system/version, installation method, and whether you use a regular release or nightly build. For mobile apps, include the device model.
- Write numbered steps that reproduce the problem, what you expected, and what happened instead. Include the affected video URL if it is public and relevant.
- Copy the exact error text and attach a screenshot or short recording if it explains the problem. Mention any settings changes or workarounds you tested.
- For problems that are hard to describe, turn on Settings → Advanced → Diagnostics → Enable diagnostic logging, reproduce the problem, then choose Copy report or Save report and attach it.
Diagnostic logs stay in memory until you copy or save them, and turning logging off deletes them. Reports leave out cookies, tokens, IP addresses, and URL parameters, but can include IDs of videos you played. Check a report before you share it.
Remove personal information from screenshots and logs. Do not attach cookies, passwords, sync recovery information, or your full viewing database to a public issue.
For help using the app, you can also ask in the Matrix community or Fluxer community.