Troubleshooting
Practical checks for debugging connections, installation, and launcher handover.
I cannot find Developer options
Look under Settings → System or Device Preferences → About. Press the Build entry seven times. Names vary by manufacturer. If a managed or ISP-provided device locks the debugging controls, this workflow may not be available on that firmware. Do not keep changing router settings to solve a firmware restriction.
My computer cannot find the TV
- Confirm the TV is on and both devices are on the same local network. A guest Wi-Fi network or isolated IoT network may prevent devices from reaching one another.
- Recheck the TV's current IP address in its network settings. An address can change after a restart.
- Enable USB debugging and Network/ADB debugging if the TV provides that switch. Watch the television for the authorization dialog and approve only your trusted computer.
- Some Google TV models use a Wireless debugging pairing code and a temporary port instead of immediately opening port 5555. Follow the pairing steps in the downloadable installation prompt.
- Never forward the ADB port through your internet router.
On macOS, a “No route to host” message can be caused by Local Network privacy. The source package includes a Python ADB client as an alternative; read docs/TROUBLESHOOTING.md under Connecting after extracting the source package before assuming the television is offline.
A USB speaker or drive stopped working
Some TV boxes change their USB-port behavior while USB debugging is enabled. Switch debugging off when the work is finished and check the device again. The launcher does not need debugging to remain on for everyday use.
The launcher build or APK installation failed
Use the complete extracted source package, not a single downloaded APK or build file. Prepare Python 3, JDK 17, Android SDK Platform 34, and Android Build Tools 34.0.0. Review the actual error instead of disabling verification or installing an unrelated APK. Some TV firmware also asks for confirmation on the screen during installation.
The extracted README.md and docs/TROUBLESHOOTING.md in the source package are the reference materials for build prerequisites and model-specific issues. The companion Windows build script and macOS/Linux build script must be placed in the extracted launcher/ directory.
The Home button still opens the old launcher
Installing the app and making it the Home owner are different steps. First verify that the new launcher can open. Have the assistant inspect which component actually handles Home and follow your exact model's notes. Keep a working launcher enabled during handover. Do not guess or disable a system package just because its name looks related.
Remote, audio, HDMI, or casting changed
Stop making changes and compare the most recent package changes with the original backup. These features can depend on manufacturer services. Use the matching restore process, then test each feature separately.
Streaming apps still show advertisements
That is expected. The project changes the system home screen and selected manufacturer services. It does not remove advertising or subscription requirements inside YouTube, Netflix, or other streaming apps.
What to include in a public issue
Share your model, region, firmware version, the failing step, and a redacted error message. Keep private addresses, device identifiers, debugging keys, credentials, and full backups out of public reports.