boneIO Documentation | Troubleshooting

Most useful command to check boneio app running with systemd.

boneIO won't start.

Check if service is running

systemctl status boneio

There are some logs which might indicate what the problem is. Always check your config, if yaml is properly formatted.

Check service logs

journalctl -u boneio --all

Check service logs live

journalctl -u boneio --all -f

You might need to customize logger. Check Logger page and then press reload logger button in Home Assistant.

Common problems since version 1.6

The browser warns that the connection is not private

This is expected: the controller uses a certificate it issued itself. Click through the warning (see Connect to your boneIO), or get rid of it for good — see HTTPS certificate.

I see a wizard instead of the panel

The controller has no administrator account yet — complete the First-time setup. Until then the display briefly shows SETUP REQUIRED every time the controller starts.

Wait a few minutes if you have tried many times — repeated wrong passwords are slowed down (ten attempts per five minutes). To reset a password, log in over SSH and run boneio accounts reset <name> — see Accounts and access.

I do not see Settings or Diagnostics

You are signed in with a read-only account. Sign in as an administrator.

Home Assistant shows the boneIO entities as unavailable after I changed an MQTT password

Home Assistant still uses the old password. In Home Assistant open Settings → Devices & Services → MQTT → Configure and type the new one. See Home Assistant connection.

The panel card in my Home Assistant dashboard is empty

Since 1.6 only the controller itself may show the panel in a frame. Add your Home Assistant address under One more address you trust in Settings → Access → Security → Embedding this panel in other sites, save, and restart boneIO. The boneIO Black add-on does not need this.

The reason is printed in the banner and in Settings → Maintenance → System migrations (the banner's button opens Software update, not the migrations). Download the support bundle (Diagnostics → Support → Download diagnostics) and send it to us on Discord.

After a power cut the page says "boneIO is starting…"

That is normal: the controller is still starting. The page refreshes itself every few seconds and opens the panel on its own — usually within a minute or two of power coming back. You do not need to press anything.

The display says "Updating" and "Do not power off."

Or Updating system with a percentage, if the display is not set up in the configuration. The controller is applying system migrations after an update, and shows how far it has got. On a controller several versions behind this can take many minutes; the panel does not answer meanwhile. Let it finish — do not unplug it.

A system update was interrupted

If the power went off or the controller restarted during an operating system update, the Operating system card says The system update was interrupted. Do not restart the controller; click Update system again — see Maintenance → Operating system.

Recovery mode

If the configuration contains an error, or boneIO crashes three times in a row while starting, the controller does not keep restarting. It opens a small recovery panel instead, at the usual address. The display shows Recovery mode and the address to open.

Sign in with your administrator account. The recovery panel shows what went wrong — for a configuration error, the file, line and column — and offers:

Config files — the YAML files in an editor, opened at the faulty line; Check config tests your fix the same way a start would, Save stores it,
Log — the service log (passwords removed),
Backups — restore an earlier configuration; the current files are archived as a new backup first,
Restart boneIO — try a normal start again.

Your outputs, buses and the MQTT broker are left alone while the recovery panel is open. If the recovery panel opened because boneIO kept crashing, the controller tries a normal start by itself after ten minutes with nobody using the panel. A configuration error is not retried: fix it and click Restart boneIO.

The recovery panel needs an administrator account; on a controller that has none, fix the configuration over SSH.

The recovery panel is in English only.

Troubleshooting