# Troubleshooting

> Fixes for tablets that stop starting, battery and vendor auto-start screens, overlay permission, USB debugging, a busy camera, voice that will not wake and dashboards that will not load.

Start with the first section. Most "Kiosky stopped on its own" problems are the manufacturer's battery manager.

## Kiosky stops, or does not start after a reboot

Several Android skins aggressively stop background apps and block apps from starting at boot. You need to allow Kiosky in three places:

1. **Battery optimisation.** In the setup wizard's **Keep running** step, tap **Allow** next to **Battery optimisation** and choose to let Kiosky run unrestricted. Without it Android may stop the kiosk in the background.
2. **The manufacturer's battery or auto-start manager**, covered below.
3. **Start on boot.** In normal-app mode, check **Settings, Lock & security, Normal app, Start on boot** is on. Locked kiosks always open on boot.

Also check **Display over other apps** (next section), which lets Kiosky reopen itself after a crash.

### Start on boot and vendor auto-start screens

In the setup wizard and in **Settings, Lock & security, Normal app**, Kiosky shows the steps for your device's manufacturer, and an **Open** or **Allow auto-start** button that jumps to the vendor's auto-start screen when it can find one. Vendor menus change between versions, so if a name below does not match, look for the closest "auto-start", "app launch", "background activity" or "battery" entry for Kiosky.

| Vendor | What to do |
|---|---|
| Honor, Huawei | Settings, Battery, **App launch**, Kiosky. Turn off **Manage automatically**, then enable **Auto-launch**, **Secondary launch** and **Run in background**. Kiosky can also open the Startup manager of the Honor or Huawei system manager. |
| Xiaomi, Redmi, Poco | Settings, Apps, Kiosky, **Battery saver**: **No restrictions**. Also enable **Autostart** (the Security app's autostart screen). |
| Oppo, Realme | Settings, Battery, Kiosky: allow **background activity** and **auto-launch**. Kiosky can also open the Oppo or ColorOS startup app list. |
| OnePlus | Settings, Battery, Kiosky: allow background activity and auto-launch. Kiosky can open OnePlus's launch manager. |
| Vivo, iQOO | Kiosky opens Vivo's **background startup manager** (also the iQOO secure app) when it exists. Allow Kiosky there, and set Kiosky to unrestricted in the battery settings. |
| Samsung | Settings, Battery, **Background usage limits**: add Kiosky to **Never sleeping apps**. |
| Motorola | Settings, Battery, **Battery usage**, Kiosky: set to **Unrestricted**. |
| Asus | Kiosky can open Asus Mobile Manager's auto-start screen. Allow Kiosky there. |

After changing these, restart the tablet once and check that Kiosky comes up by itself.

## Display over other apps

Kiosky needs **Display over other apps** to:

- come to the front by itself in normal-app mode (for a remote popup, a camera or a loaded page);
- reopen after a crash or a kill, and in single-app mode show the exit corner.

If it is missing, the wizard says "Allow 'Display over other apps' so Kiosky can reopen itself…" and shows an **Allow** button. In Settings the same button is on the **Normal app** card and the **Kiosk mode** card. Without the permission, remote commands still run, but Kiosky cannot raise itself above another app.

## USB debugging and file transfer

You need USB debugging for the full lock command.

1. Open **Settings, About tablet** and tap **Build number** seven times to enable Developer options. On some skins it is under Software information.
2. Open **Developer options** and turn on **USB debugging**.
3. Connect the cable. If the tablet asks for a USB mode, choose **File transfer** (MTP). Some tablets only expose `adb` in that mode, not in "Charging only".
4. Accept the **Allow USB debugging?** prompt on the tablet and tick **Always allow from this computer**.
5. On the computer, `adb devices` should list the tablet as `device`. `unauthorized` means you have not accepted the prompt yet. An empty list means the cable, the port or the USB mode is wrong. Try another cable, as many are charge-only.

If `dpm set-device-owner` fails with a message about accounts or users, remove every account in **Settings, Accounts** (including Google) and run it again. See [Choosing a mode](modes.md#full-lock-device-owner).

## Camera is busy or unavailable

Android lets only one app use the camera at a time.

- Close other apps that use the camera (video calls, camera apps) and try again.
- Check **Settings, Camera & sensors, Camera permission** shows **Granted**.
- If **Camera snapshot** or the stream says "Camera unavailable" (`503`), the camera did not start within 15 seconds or is held by another app. Disable motion or face detection to see whether Kiosky itself was the one holding it, then re-enable one at a time.
- The live stream allows 2 viewers at once. A third gets `503` "Too many stream viewers".
- Restart the app from the admin page or with the `restart_app` command if it keeps failing.

## Voice does not wake

**Settings, Voice** shows a status chip with the reason. The values and what to do:

| Status | Fix |
|---|---|
| Voice is turned off | Turn on **Enable voice** and tap **Save voice**. |
| Microphone is muted | Turn **Microphone** on, here or with the Home Assistant switch. |
| Microphone permission not granted | Tap **Allow microphone**, or open app settings. |
| Home Assistant URL or token missing | Enter the URL and a long-lived token and save. |
| Paused while the screen is off | Turn off **Listen only while the screen is on**, or wake the screen. |
| Paused while not charging | Turn off **Listen only while charging**, or plug the tablet in. |

If the chip says "Listening for the wake word" but nothing happens:

- Say the wake word clearly and closer to the tablet. Accuracy drops with distance and room noise.
- Lower **Wake threshold** a little (lower wakes more easily). Try another wake word: Okay Nabu, Hey Jarvis or Hey Mycroft.
- Make sure your Home Assistant Assist pipeline has speech-to-text and text-to-speech. Leave the pipeline id blank to use the preferred one.
- Use a Home Assistant address with a certificate Android trusts. Self-signed HTTPS does not work for voice.
- Allow Kiosky to run in the background (see the first section). The microphone service can only start while Kiosky is visible, so after the app was killed it resumes listening once Kiosky is back on screen.
- While listening, a **MIC** pill and a "Microphone on" notification show. If they are missing, the microphone is off.

## The dashboard does not load

Kiosky shows a plain-language message with the technical code in small print, and retries by itself. Use **Retry now** to try straight away.

| Message | What it means |
|---|---|
| No internet connection | Wi-Fi is off or the network changed. |
| That address couldn't be found | Wrong address or a DNS problem. `homeassistant.local` needs mDNS on the network. Try the IP address. |
| The dashboard took too long to answer | The server is busy, asleep or unreachable. |
| The server refused the connection | The service is down, restarting or on a different port. |
| The connection dropped while loading the page | A flaky network. |
| A secure connection couldn't be made | The certificate is invalid, expired or not trusted by Android. |
| The server is having a problem | An HTTP 5xx from the server. |

Other checks:

- In setup, **Test connection** tells you whether the tablet can reach the address. The tablet may be on a different network or VLAN from the server.
- A page that redirects to another host (a login or SSO page) needs that host under **Extra allowed hosts**. See [Dashboards & browser](dashboards.md#allowed-hosts). Navigation to other hosts is blocked.
- A `load_url` or `popup` that does nothing is usually a host that is not allowed. Watch for a `command_rejected` event.
- If the Home Assistant login screen appears, check the address and token under **Dashboard, Home Assistant sign-in**. A token is not sent to a plain `http` address on a public network; use `https`.
- If the Home Assistant header or sidebar is missing and you cannot get it back, double-tap within the top 48 pixels of the screen, or set **Hide Home Assistant chrome** to **Show**.

## Connections

**The REST API does not answer.** Check **Settings, Connections, Remote access** shows **Running on port ...**, use the IP address shown there, and that the tablet and your computer are on the same network. `401` means a wrong token, and `429` means too many wrong tokens: wait for the `Retry-After` seconds. See the [REST API reference](rest-api.md).

**The tablet does not appear in Home Assistant.** Check the MQTT chip says **Connected**, **Home Assistant discovery** is on, and that your discovery prefix in Home Assistant is the default `homeassistant`. Subscribe to `kiosk/#` on the broker to confirm messages arrive. See the [MQTT reference](mqtt.md).

**A command does nothing.** Subscribe to `kiosk/<id>/event` and look for `command_rejected`. It names the reason, for example "Remote unlock is turned off on this tablet".

**I changed the device name and my topics changed.** The topics and entity ids follow the device name. Update your automations, or rename the device back.

## Still stuck

Open **Settings, Device, Logs** to see recent log lines (tokens and passwords are masked), then **Save to file** or **Share** them when you ask for help. Email `support@enraio.com`.