Troubleshooting¶

Two commands find almost everything

sudo kinuxota status and sudo kinuxota logs -n 100. Start there.

Start on the device with kinuxota status. With sudo it shows everything:

$ sudo kinuxota status
Version:   2.0.0
Service:   active (enabled)
Enrolled:  yes
Device ID: 6ae29bfce1fb8a3a01563db9
MQTT:      connected since 2026-11-01 10:12:03 (1 connect)
Dashboard: "kiosk-lobby" is ONLINE

Then read the agent's log:

sudo kinuxota logs -n 100     # the last 100 lines
sudo kinuxota logs -f         # follow

The device shows Offline¶

`kinuxota status` says	What to do
`Service: inactive` or `failed`	Start it: `sudo systemctl restart kinuxota`, then read `sudo kinuxota logs -n 50`.
`Enrolled: no`	Enroll it: `sudo kinuxota enroll --key <API_KEY>`.
`Dashboard: API key rejected (device deleted? enroll again)`	The device was deleted in the dashboard, or the key is wrong. Add the device again and enroll with the new key.
`Dashboard: unreachable (...)`	The device cannot reach `https://back.kinuxota.com`. See Firewalls and proxies.
`Dashboard: server error HTTP <n>`	The service has a problem. Try again later; the agent keeps its results until it can send them.
`MQTT: polling, reconnecting: <reason>`	The live connection to `mqtt.kinuxota.com:27202` fails. Commands still arrive by polling the API, more slowly. Check that outbound port 27202 is open.
`MQTT: agent not running`	The service is not running: see the first row.

When the live connection works, the log has a line Connected to mqtts://mqtt.kinuxota.com:27202 as ....

Firewalls and proxies¶

The device needs outbound connections to:

back.kinuxota.com, port 443 (HTTPS);
mqtt.kinuxota.com, port 27202 (MQTT over TLS);
apt.kinuxota.com, port 443 (HTTPS), to install and update.

Check them from the device:

curl -sS -o /dev/null -w '%{http_code}\n' https://back.kinuxota.com/api/health
curl -sS -o /dev/null -w '%{http_code}\n' https://apt.kinuxota.com/kinuxota.gpg
timeout 5 bash -c '</dev/tcp/mqtt.kinuxota.com/27202' && echo "port 27202 open"

A firewall that inspects TLS and re-signs certificates breaks the connection: the agent checks the server certificates. Let these three hosts through without inspection.

apt through a proxy. Installing and updating use apt, so apt's own proxy setting applies, for example /etc/apt/apt.conf.d/95proxy with Acquire::https::Proxy "http://proxy.example:3128";.

Install and update problems¶

Message	What to do
`kinuxota: unsupported system (...)`	The installer supports Ubuntu 22.04, 24.04, 26.04, Debian 12, 13 and Raspberry Pi OS 12, 13.
`kinuxota: this device is ARMv6 ...`	Raspberry Pi 1, Zero and Zero W are not supported.
`kinuxota: please run as root (use sudo).`	Run the installer with `sudo sh`.
`kinuxota enroll: the server rejected this API key. Copy it again from the dashboard.`	Copy the key again, or add the device again for a new key.
`kinuxota enroll: a valid --key is required (64 hexadecimal characters from the dashboard)`	The key is incomplete: copy all 64 characters.
An update message	See the messages on Update the agent.

A command or script does not finish¶

The device must be Online to start a command; a command sent to an offline device waits until the device connects.
Each command has a timeout; a command that runs longer is stopped and reported as failed.
Open the device's command history in the dashboard for the output and the exit code.

Still stuck¶

Collect sudo kinuxota status and sudo kinuxota logs -n 200 and send them to support (see the FAQ).