Troubleshooting

Common failure points from flash → first boot → network → updates. Prefer Ethernet when diagnosing Wi‑Fi. Dev-only recovery scripts from the git repo are not the end-user path — reflash a known-good image if the stick itself is corrupt.

USB will not boot

• Confirm the machine is in UEFI mode (disable Legacy/CSM if possible).
• Use the firmware boot menu and pick the USB UEFI entry (label often LOCALONEUSB), or Boot from file → EFI/BOOT/BOOTX64.EFI.
• Try another port (USB2 vs USB3), another stick, or reflash after verifying SHA256SUMS.
• If Secure Boot rejects the image, disable it temporarily to confirm the stick is otherwise fine — then use a signed release image.

# On the machine you used to flash — confirm image integrity
sha256sum -c SHA256SUMS --ignore-missing

# Reflash (Linux helper)
sudo ./flash-localone-usb.sh ./localone-*-amd64.img.xz

Cannot join LocalOne-Setup / no wizard

• Wait 1–2 minutes after boot for the AP and control plane to come up.
• Forget other Wi‑Fi networks on the phone; join LocalOne-Setup only. Open the captive portal or try http://192.168.4.1.
• Plug in Ethernet with DHCP — setup may skip the hotspot when a wired uplink exists.
• If you already finished setup once, the hotspot is intentionally disabled. Use the LAN address / *.local name instead.

Install to disk failed or machine will not boot from NVMe

• Install wipes the selected disk. Wrong disk selection is unrecoverable without backups — always confirm the model/size in the UI.
• Leave the USB in until the UI says install finished, then remove it and reboot.
• Firmware boot order should prefer the internal NVMe EFI entry after install. If you land in a GRUB rescue shell, boot the USB again and re-run install only if the disk was partially written — or reflash USB and start over on a clean target.
• Twin LVM volume groups / UUID clashes are exactly what the rsync installer avoids; do not dd the stick onto NVMe as a workaround.

Cannot reach the dashboard on the LAN

• Try IP from the router DHCP list, then https://localone.local / https://<hostname>.local.
• mDNS (.local) often fails across VLANs or guest Wi‑Fi — use the IP or Ethernet on the same subnet.
• Accept / install the LocalOne CA via Trust HTTPS so browsers stop blocking the self-signed cert.

# From another computer on the LAN
ping -c2 localone.local
curl -vkI https://localone.local

# On the appliance (keyboard/SSH if enabled)
ip -br a
systemctl status localone-control-plane.service --no-pager
journalctl -u localone-control-plane.service -n 100 --no-pager

Setup Wi‑Fi keeps coming back after reboot

Onboarding did not fully complete, or setup-complete was cleared. Finish the wizard on the LAN UI, confirm home Wi‑Fi works, then reboot once. Ethernet recovery: cable in → browse by IP → finish setup.

App install / marketplace fails

• Appliance needs outbound HTTPS to marketplace.getlocalone.com (or your LOCALONE_STORE_URL).
• Signature / checksum errors mean a bad download or mismatched store keys — retry after network is stable; do not bypass verification.
• Disk full or missing mount: check Storage, free space, and the app's configured data path.

curl -fsS https://marketplace.getlocalone.com/api/apps | head -c 200
df -h
docker ps -a

Control-plane update failed

• Dashboard → Updates → Failed → read the error → fix DNS / store reachability → Retry (refreshes the script URL).
• Check for updates again if the store moved to a new public base URL.

curl -fsS -o /dev/null -w '%{http_code}\n' \
  https://marketplace.getlocalone.com/api/updates/check?current=1.0.0
# HTTP status depends on API shape — connection errors matter more than body

journalctl -u localone-control-plane.service -n 120 --no-pager | tail -80

Still stuck

Re-walk Flash USB → First boot with a verified image. Capture: hardware model, firmware (UEFI/Secure Boot), which step failed, and the last ~50 lines of journalctl -u localone-control-plane.