> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iotmanager.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and how to resolve them

## Installation fails

The installer keeps a detailed log at `/tmp/iotmanager-install.log` on the device — the on-screen message only ever shows a short summary, but this file has the real error (failed download, registration failure, missing dependency, etc.).

```bash theme={null}
cat /tmp/iotmanager-install.log
```

**Registration token expired** — tokens are valid for 15 minutes. Generate a new one from the **Add New Device** button and re-run the install command.

**Stuck at "Running installer..."** — this is normal for slower connections or lower-powered devices; it can take up to a couple of minutes. The spinner just means it's still working — it isn't stuck.

## Docker / NetworkManager not found

If a panel in the dashboard says Docker or NetworkManager isn't installed, it'll suggest the exact install command for your device's distribution (`apt`, `apk`, `dnf`, `pacman`, or `zypper`). These are optional — the agent works fully without either; only the Services/container panel and Network panel depend on them respectively. See [Prerequisites](/prerequisites).

## Device shows as offline

* Check the device still has outbound network access — see [Firewall Rules](/firewall-rules) for exactly what's needed.
* Check the agent is actually running:
  ```bash theme={null}
  systemctl status iotmanager-agent   # systemd
  rc-service iotmanager-agent status  # OpenRC
  ```
* If the device was installed with no supported init system detected, the agent runs as a plain background process and won't survive a reboot on its own — check whether it's still running (`pgrep iotmanager-agent`) and, if not, re-run the install command to bring it back up.

## Terminal or file manager not loading

If you see a device that's been running an older agent version, dashboard tabs that shell out (device info, network, services) can occasionally hang rather than showing an error. This was a real bug in early builds and is fixed — if you still see it, the device's agent binary is likely stale. Re-run the registration command to update it in place (it's safe to run again on an already-registered device).

## Removing a device doesn't fully clean up

Uninstalling from the **Devices** page should remove the agent, its service files, and all state directories automatically — the device only needs to be online for this to complete. If a device was offline when you tried to remove it, bring it back online and remove it again.

## Still stuck?

Reach out at [iotdevicemanager@gmail.com](mailto:iotdevicemanager@gmail.com) with the device's ID and, if relevant, the contents of `/tmp/iotmanager-install.log`.