CleanYourTV troubleshooting
The CleanYourTV problems people hit most, grouped by stage, with what to do. Based on the official troubleshooting notes collected from contributors.
Connecting to the TV
| Problem | What to do |
|---|---|
Mac: adb connect says "No route to host" | Local Network privacy blocks the adb binary. Use tools/tv.py instead. |
| No Wireless debugging toggle | Normal on some TVs, Xiaomi among them. USB debugging alone opens network ADB on port 5555. |
| Port 5555 never opens | Some Google TV sets need Wireless debugging pairing first: adb pair, adb connect, then adb tcpip 5555. |
| Developer options missing or asks for a password | Seen on ISP boxes. An app that opens activities by name can often reach the developer screen anyway. |
| USB debugging greyed out | Some carrier firmware removes both switches. Without one of them, CleanYourTV cannot connect. |
| Connection times out on a guest or IoT network | The router blocks the computer. Allow tcp/5555 from your computer to the TV only, temporarily. |
| "Allow USB debugging?" keeps coming back | Dismiss the queued prompts with Back; the tool now reuses your existing adb key. |
| USB drive, speaker or Ethernet adapter dies | Some boxes switch the USB port to debug mode. Finish in one sitting, then turn debugging off. |
During the debloat
| Problem | What to do |
|---|---|
| Home lands on a factory test app | The stock launcher went first. Re-enable it, install the new launcher, then disable the stock one. The install script orders this for you. |
| Google TV crash-loops after the stock launcher is disabled | The setup wizard (setupwraith) takes Home. Disable it too, but check your Wi-Fi first (next row). |
| TV drops off Wi-Fi when setupwraith is disabled | The network was saved during setup and belongs to the wizard. Re-join it in Settings first. |
| Only the first of several commands ran | Chained pm commands can stop silently. Run one per call. |
| Every disable is refused | Seen on the 2015 Fire TV Box. Nothing can be done there. |
| Input key and HDMI-CEC stop working | Opening a hidden factory app can switch them off on some sets. Do not open unknown factory apps. |
Installing the launcher
| Problem | What to do |
|---|---|
INSTALL_FAILED_OLDER_SDK | The TV runs Android older than 8.0. The launcher cannot run there; the debloat still can. |
| Play Protect blocks the launcher as "built for an older version of Android" | That came from an old checkout targeting SDK 29. Update the repository and rebuild; the launcher targets SDK 34 now. |
adb install hangs on Android 14 | It waits for an on-screen confirmation. Push the APK and run pm install -r instead. |
| Launcher installed but does not own Home | Some China-market Xiaomi and TCL sets filter out third-party Home apps. Re-enable the stock launcher and check your model’s device notes before trying again. |
| No on-screen keyboard | The default input method points at a keyboard that is not installed (seen on Xiaomi). Set Gboard as the input method with ime set. |
| Remote buttons (Input, YouTube, settings) stop working | The stock launcher handled them. The optional key helper service brings them back. |
After the setup
| Problem | What to do |
|---|---|
| Ads are back after an update | Run tools/check.py --fix with your list. See restore and updates. |
| Phone casting stopped | On Chromecast and the Google TV Streamer, setupwraith is needed for casting. |
| Clock is off by 30 or 60 minutes | The TV picked a neighbouring zone or has old time zone data. Turn off automatic time zone and set yours by hand. |
| Google TV home comes back after a few presses | Seen on XGIMI: a remote-key service re-enables the stock launcher on every app button. Check the XGIMI lists for how it was handled. |
The full, detailed notes are in the official troubleshooting document. Questions about your TV go to GitHub Discussions.
Quick fixes
"No route to host" on a Mac.
macOS Local Network privacy blocks the standard adb binary. Use the project’s tools/tv.py, which does not use it.
The Home button opens a factory test app or a blank screen.
The stock launcher was disabled before the new one took over. Re-enable the stock launcher, for example tools/tv.py 'pm enable --user 0 com.google.android.apps.tv.launcherx' on Google TV, then install the new launcher first.
The TV dropped off Wi-Fi after the debloat.
On Google TV the Wi-Fi network saved during setup belongs to the setup wizard. Re-enable setupwraith, join the network again in Settings, then disable it.
Casting from my phone stopped working.
Disabling setupwraith on Chromecast and the Google TV Streamer costs phone casting. Re-enable it if you need casting.
The mic button does nothing.
The voice assistant package was disabled. Re-enable it with the restore script, or apply the list again with that line commented out.