Something not right?Start here.

On first run the app scans your local network for Home Assistant instances. If nothing appears:

• Confirm the TV and Home Assistant are on the same network and VLAN. Discovery does not cross subnets.
• Enter the address by hand instead — the setup screen accepts a full URL, for example http://192.168.1.10:8123.
• For a remote instance, the URL must be HTTPS with a valid certificate. Self-signed certificates will not connect.

First-run configuration guide →

Better to create a dedicated user for the TV — call it something like Television. It keeps the TV’s activity separate in your logbook, and you can revoke it without touching your own account.

In Home Assistant: Settings → People → Users → Add User. Set Local access only to on, since a TV never leaves the house.

You sign in with your normal login. No long-lived access token is needed.

Check the connection status indicator first — the app shows a dot when the server is unreachable.

• Give the TV a static IP or DHCP reservation. A changed address is the most common cause.
• If Home Assistant sits behind a reverse proxy, make sure it permits WebSocket upgrades. The app keeps a live WebSocket open; without it, state never updates.
• Android 14 is aggressive about killing background services. Versions from 2026.3.2 (145) recover in seconds rather than minutes — update if you are older than that.

Both are overlays, so they need Display over other apps. Without it the app runs but nothing can draw on top of what you are watching.

In the app: Settings → Set up → Enable, then toggle HA TV Dashboard on.

Overlay permission walkthrough →

Some manufacturers hide the setting entirely — the NVIDIA Shield is the known case. Grant it over ADB instead.

Enable USB debugging on the TV, then from a computer on the same network:

adb connect <your-tv-ip>
adb shell appops set io.homeassistant.companion.androidtv SYSTEM_ALERT_WINDOW allow

This is Android’s behaviour, not a bug in the app.

Since Android 6.0.1 the Play Store may auto-grant SYSTEM_ALERT_WINDOW to apps installed from the store, and re-grant it after updates or a data reset. A sideloaded APK gets no such trust: Android requires you to grant it manually, every time the app’s state is wiped.

So after any Clear Data, or some updates, re-grant it by hand or with the ADB command above. Installing from Google Play avoids the problem entirely.

Install from Google Play →

Android TV gives an app no other way to see remote-control key presses while it is in the background. The service reads D-pad and hardware button events only. It cannot see screen content.

If you do not use remote key actions, you can leave it off; everything else keeps working.

• Re-check the Accessibility Service — Android silently disables it after some updates, and after a factory reset.
• Some TVs restrict accessibility services after a reboot. Toggle it off and on once to confirm.
• Battery optimisation can suspend the service. Exclude HA TV Dashboard in your TV’s battery or power settings if the option exists.

Dedicated service buttons on many remotes are wired to launch their app at the firmware level, before any app can intercept them. Those are usually unmappable.

Pick a button with no fixed function instead — coloured buttons, or a double-press of one you already use.

Avoid mapping the D-pad, OK, Back, Home or Power. If you already have, reset the app to clear the mapping:

Device Settings → Apps → All Apps → HA TV Dashboard → Force Stop, then Clear Cache and Clear Data.

Full reset procedure →

A known issue on Chromecast with Google TV, fixed in 2026.3.2 (145). Update the app first.

Rich and remote-triggered notifications need the persistent background connection, so confirm the app is allowed to run in the background and is excluded from battery optimisation.

Work outwards from the connection:

• Import the Connection Status to TV blueprint and run it. If that does not appear, the problem is the link to the TV, not your automation.
• Check the TV’s device name in your automation matches the name you gave it during setup.
• Confirm the device still exists under Settings → Devices & Services → Mobile App in Home Assistant.

Blueprints repository → · one-click imports →

That happens when the app is reset and re-registers under a new name. Delete the stale registration:

Open http://<your-ha-ip>:8123/config/integrations/integration/mobile_app, find the old device, and choose Delete from its overflow menu. You can then reuse the original name.

Four stream types are supported — WebRTC, RTSP, HLS and MJPEG — and not every camera works well over all of them.

• For RTSP, try switching the transport mode between TCP and UDP. It is configurable per feed. UDP is lighter; TCP survives a congested network far better.
• MJPEG support was added in 2026.6.0 (150) — update if a MJPEG feed does nothing.
• Test the stream URL in VLC first. If VLC cannot play it, the app will not either.

Latency is mostly the stream’s own doing, not the app’s. Use your camera’s sub-stream or low-resolution profile for popups — a 4K main stream will always be slow to start.

WebRTC generally gives the lowest latency where your camera offers it; HLS is the slowest by design, often several seconds behind.

Only relevant if you sideload — Google Play picks the right build automatically.

Find your architecture with:

adb shell getprop ro.product.cpu.abi

Device	Build
NVIDIA Shield	arm64-v8a
Chromecast with Google TV	armeabi-v7a
Google Streamer	armeabi-v7a
Android emulator	arm64-v8a

No ADB? Droid Hardware Info or CPU-Z will show the ABI under System or CPU. The universal APK works everywhere but is roughly three times the download.

Every release and APK →

An old bug on Chromecast with Google TV, fixed in 2025.2.1 (122). If you are seeing it, you are running something very old — update from Google Play.

In the app: Settings → App Config → Developer Mode, enable it, then enable Log to file. On some devices you must force stop and reopen the app before logging starts.

The log file is written to the app’s folder on internal storage as app_logs.txt. Pull it with:

adb connect <your-tv-ip>
adb shell ls /sdcard/Documents/HATVDash
adb pull /sdcard/Documents/HATVDash/app_logs.txt .

For system-level logs, run adb logcat > deviceLogs.txt, reproduce the problem, then stop it with Ctrl+C.

Turn Log to file back off when you are done — it grows without limit.

Full logging guide →

Open an issue with the exact steps to reproduce, your device model, the app version from Settings → About → Device, and a log if you have one.

Raise an issue on GitHub →