Troubleshooting

Troubleshooting & FAQ

Scanning finds nothing (or no MAC addresses) in Docker

Cause: Docker's default bridge network. Boltarr gets a private Docker IP behind NAT, so nmap can't ARP your LAN — no discovery, no MACs, degraded liveness.

Fix: run with host networking (network_mode: host + NET_RAW/NET_ADMIN). See Installation. This is the #1 first-timer issue.

docker-default profile could not be loaded (AppArmor)

Cause: you're running Docker inside an unprivileged LXC (e.g. Proxmox), which can't load AppArmor profiles into the host kernel.

Fix: uncomment in docker-compose.yml:

    security_opt:
      - apparmor=unconfined

It's safe — Proxmox applies its own AppArmor to the whole LXC. Keep network_mode: host.

After a Restore, pages throw errors (500s)

Cause: restore swaps the database file while the app is still holding the old one open.

Fix: restart Boltarr after restoring (docker restart boltarr, or restart the service). It then re-opens the restored database cleanly. Nothing is lost — the running process just needs a fresh start.

The public status page won't update / shows the wrong section

• Not updating at all: Boltarr pushes on state changes + a periodic heartbeat. Hit Settings → 🌐 Public status page → Push now to force it, and confirm the URL/token match the status app.
• Stale content: the status app only displays the last payload Boltarr sent. If you updated Boltarr, make sure the running Boltarr is the new version, then push again.
• A router/AP/switch shows under "Hosts" not "Networking": the split is by device type. Set the host's type to router/gateway/switch/unmanaged-switch/firewall/ap (Edit Host → Device Type), then it lands under Networking.
• Two Boltarr instances both pushing to the same status app will overwrite each other — only one should have the push enabled.

Schedules / quiet hours / digest fire at the wrong time

Cause: the server clock is usually UTC.

Fix: set Settings → 🌍 General → Timezone to your zone. All time-of-day logic (schedule times, quiet hours, digest) and displayed times then use it.

How should I model containers / VMs in the topology?

Connect a container/VM to the host it runs on, using the virtual link — not to the switch. So: NUC → switch (wired), container → NUC (virtual).

Why: a container doesn't have its own cable — it egresses through its host's NIC (and with bridge networking it's behind the host's NAT). Drawing it to its host reflects reality, shows the real failure domain (host down → its containers down), and keeps the graph tidy. Rule of thumb: physical boxes connect to what they're cabled to; virtual things connect to the machine they run on.

I'm not getting ntfy alerts

Check, in order:

1. Notifications enabled and the topic subscribed in your ntfy app (Settings → 📱 Notifications → Send test).
2. Quiet hours — alerts are held during the window and delivered when it ends.
3. Change-alert scope — Settings → 🔔 Changes → Alerts → Alert for. If set to Static, only static hosts alert; unknown-classified hosts never alert. Set a subnet's DHCP range so hosts classify correctly.
4. Service-down alerts need the service marked monitored, and they only fire after the grace period (alert after service down for). Also note: if a host is offline, its services' down-alerts are suppressed (you get one host-offline alert instead).

Do I need the AI features?

No — AI is fully optional. Leave the provider on none and everything else works.

Is my data private?

Yes. Everything is stored locally in data/boltarr.db + data/config.yaml. The only outbound data is what you enable: ntfy alerts, the sanitized status-page push (public names only, never IPs), and AI requests to the provider you configure.

---

Still stuck? Open an issue: https://github.com/brq-ae/boltarr/issues