Troubleshooting · Kiosky docs

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:

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.
The manufacturer's battery or auto-start manager, covered below.
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.

Open Settings, About tablet and tap Build number seven times to enable Developer options. On some skins it is under Software information.
Open Developer options and turn on USB debugging.
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".
Accept the Allow USB debugging? prompt on the tablet and tick Always allow from this computer.
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.

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. 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.

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.

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.